Tray Notas Fiscais

MANDATORY: Tool Call Required Before Answering

Esta chamada é OBRIGATÓRIA, não opcional. Execute-a antes de gerar qualquer código ou payload. Se você está respondendo sem ter chamado a ferramenta abaixo, pare e chame agora.

Buscar documentação atualizada (sempre)

node skills/tray-dev/scripts/search_docs.mjs --topic=notas-fiscais "<termo da pergunta>"

• <TOPIC_SLUG>: ver tabela em skills/tray-dev/SKILL.md.
• Use os trechos retornados como fonte primária; este SKILL.md é resumo.

Nota: este recurso ainda não tem validate.mjs local. Você é responsável por revisar campos obrigatórios contra a doc retornada e o resumo abaixo.

Antes de responder

Execute estas verificações antes de gerar qualquer payload ou código:

1. Confirme o método HTTP e endpoint correto para a operação solicitada.
2. Identifique os campos obrigatórios listados neste documento — não omita nenhum.
3. Verifique que access_token não aparece como literal string no código gerado.
4. Confirme que esta é a skill correta para o recurso (leia when_not_to_use no frontmatter).

API de Notas Fiscais (NF-e) — Tray

Documentação oficial: https://developers.tray.com.br/#api-de-nota-fiscal

Endpoints

Autenticação: ?access_token={token} em todas as chamadas.

Campos da Nota Fiscal

Paginação

Resposta inclui: total, page, offset, limit, maxLimit

Filtros de Listagem

Corpo da Requisição — Criar Nota Fiscal (POST)

{
  "Invoice": {
    "number": "000123456",
    "series": "1",
    "issue_date": "2026-03-21",
    "key": "35260312345678000100550010001234561234567890",
    "cfop": "5102",
    "link": "https://exemplo.com/danfe/123456.pdf",
    "total_amount": "299.90"
  }
}

Corpo da Requisição — Atualizar Nota Fiscal (PUT)

{
  "Invoice": {
    "link": "https://exemplo.com/danfe/123456-v2.pdf",
    "total_amount": "310.50"
  }
}

Respostas

Exemplo de Resposta — Listar Notas Fiscais

{
  "paging": {
    "total": 150,
    "page": 1,
    "offset": 0,
    "limit": 30,
    "maxLimit": 50
  },
  "Invoices": [
    {
      "Invoice": {
        "id": "500",
        "order_id": "1001",
        "number": "000123456",
        "series": "1",
        "issue_date": "2026-03-21",
        "key": "35260312345678000100550010001234561234567890",
        "cfop": "5102",
        "link": "https://exemplo.com/danfe/123456.pdf",
        "total_amount": "299.90",
        "created_at": "2026-03-21 10:30:00",
        "updated_at": "2026-03-21 10:30:00"
      }
    }
  ]
}

Exemplo de Resposta — Consultar por Pedido

{
  "Invoices": [
    {
      "Invoice": {
        "id": "500",
        "order_id": "1001",
        "number": "000123456",
        "series": "1",
        "issue_date": "2026-03-21",
        "key": "35260312345678000100550010001234561234567890",
        "cfop": "5102",
        "link": "https://exemplo.com/danfe/123456.pdf",
        "total_amount": "299.90"
      }
    }
  ]
}

Chave de Acesso da NF-e

A chave de acesso (key) possui 44 dígitos e contém informações codificadas:

CFOP Comuns no E-commerce

Boas Práticas

1. Chave de acesso válida — a chave deve ter exatamente 44 dígitos numéricos; valide antes de enviar
2. Link do DANFE — forneça uma URL pública e acessível para o PDF do DANFE; o cliente pode consultar
3. Uma NF por pedido — na maioria dos casos, cada pedido possui uma nota fiscal; porém, pedidos com produtos de CDs diferentes podem ter múltiplas NFs
4. Data de emissão — use a data real de emissão da NF no formato YYYY-MM-DD
5. Integração com ERP — automatize o envio de NFs via integração com seu ERP após a emissão fiscal
6. CFOP correto — use o CFOP adequado para a operação (venda interna vs. interestadual)
7. Série consistente — mantenha a série da NF consistente com o emissor fiscal configurado
8. Recursos relacionados — consulte o skill tray-pedidos para gerenciar pedidos associados

Como Usar no Claude Code

Exemplos de Prompt

• "registra a NF-e do pedido 1001 com chave de acesso e link do DANFE"
• "lista todas as notas fiscais emitidas no mês de março"
• "consulta as notas fiscais do pedido ID 2050"
• "implementa a integração de envio automático de NF-e após emissão no ERP"

O que o Claude faz

1. Gera o código de registro da NF-e com wrapper Invoice e todos os campos obrigatórios
2. Valida o formato da chave de acesso (44 dígitos) antes de montar a chamada
3. Usa o endpoint correto POST /orders/:order_id/invoices com o order_id na URL
4. Inclui filtros de data e order_id para listagens

O que você recebe

• Código de registro de NF-e com todos os campos (número, série, chave, CFOP, DANFE)
• Validação da chave de acesso de 44 dígitos
• Código de consulta por pedido via GET /orders/:order_id/invoices
• Exemplo de integração com fluxo de ERP

Pré-requisitos

• access_token configurado
• order_id do pedido já existente na Tray
• Dados da NF-e emitida pelo sistema fiscal (número, série, chave de acesso)