| name | tray-notas-fiscais |
| description | API de Notas Fiscais (NF-e) da Tray. Utilize quando o desenvolvedor precisar gerenciar notas fiscais eletrônicas associadas a pedidos, incluindo listagem geral, consulta por ID, consulta por pedido, criação e atualização. Inclui campos como número, série, chave de acesso, CFOP, link do DANFE e valor total, essenciais para integração com ERPs e sistemas fiscais.
|
| when_to_use | Use quando o desenvolvedor mencionar: nota fiscal, NF-e, DANFE, chave de acesso, CFOP, número de NF, GET /fiscal_notes, POST /fiscal_notes, integração com ERP fiscal, emitir nota ou vincular NF a pedido.
|
| when_not_to_use | Não use para criar pedidos (use tray-pedidos) nem para dados de pagamento (use tray-pagamentos). Use apenas para registrar ou consultar NF-e associadas a pedidos.
|
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:
- Confirme o método HTTP e endpoint correto para a operação solicitada.
- Identifique os campos obrigatórios listados neste documento — não omita nenhum.
- Verifique que
access_token não aparece como literal string no código gerado.
- 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
| Método | Endpoint | Descrição |
|---|
| GET | /invoices | Listagem de notas fiscais com paginação e filtros |
| GET | /invoices/:id | Consultar nota fiscal por ID |
| GET | /orders/:order_id/invoices | Consultar notas fiscais de um pedido |
| POST | /orders/:order_id/invoices | Cadastrar nota fiscal para um pedido |
| PUT | /invoices/:id | Atualizar dados da nota fiscal |
Autenticação: ?access_token={token} em todas as chamadas.
Campos da Nota Fiscal
| Campo | Tipo | Obrigatório | Descrição |
|---|
id | number | — | ID da nota fiscal (retornado pela API) |
order_id | number | — | ID do pedido associado (definido na URL no POST) |
number | string | Sim | Número da nota fiscal |
series | string | Sim | Série da nota fiscal (ex: "1", "001") |
issue_date | date | Sim | Data de emissão (formato: YYYY-MM-DD) |
key | string | Sim | Chave de acesso da NF-e (44 dígitos) |
cfop | string | Não | Código Fiscal de Operações e Prestações (ex: "5102", "6102") |
link | string | Não | URL do DANFE (PDF da nota fiscal) |
total_amount | decimal | Não | Valor total da nota fiscal |
created_at | datetime | — | Data de criação do registro |
updated_at | datetime | — | Data da última atualização |
Paginação
| Parâmetro | Descrição |
|---|
limit | Itens por página (máximo 50, padrão 30) |
page | Número da página |
Resposta inclui: total, page, offset, limit, maxLimit
Filtros de Listagem
| Filtro | Tipo | Descrição |
|---|
order_id | number | Filtrar por ID do pedido |
number | string | Filtrar por número da NF |
issue_date | date | Filtrar por data de emissão |
created_at | date | Filtrar por data de criação |
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
| Operação | Código | Mensagem |
|---|
| Criação | 201 | {"message": "Created", "id": 500, "code": 201} |
| Atualização | 200 | {"message": "Saved", "id": 500, "code": 200} |
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:
| Posição | Tamanho | Descrição |
|---|
| 1-2 | 2 | Código da UF |
| 3-6 | 4 | Ano e mês de emissão (AAMM) |
| 7-20 | 14 | CNPJ do emitente |
| 21-22 | 2 | Modelo do documento (55 = NF-e) |
| 23-25 | 3 | Série |
| 26-34 | 9 | Número da NF |
| 35-43 | 9 | Código numérico |
| 44 | 1 | Dígito verificador |
CFOP Comuns no E-commerce
| CFOP | Descrição |
|---|
5102 | Venda de mercadoria (operação interna — mesmo estado) |
6102 | Venda de mercadoria (operação interestadual) |
5405 | Venda de mercadoria com ST (substituição tributária) — mesmo estado |
6404 | Venda de mercadoria com ST — interestadual |
Boas Práticas
- Chave de acesso válida — a chave deve ter exatamente 44 dígitos numéricos; valide antes de enviar
- Link do DANFE — forneça uma URL pública e acessível para o PDF do DANFE; o cliente pode consultar
- 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
- Data de emissão — use a data real de emissão da NF no formato YYYY-MM-DD
- Integração com ERP — automatize o envio de NFs via integração com seu ERP após a emissão fiscal
- CFOP correto — use o CFOP adequado para a operação (venda interna vs. interestadual)
- Série consistente — mantenha a série da NF consistente com o emissor fiscal configurado
- 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
- Gera o código de registro da NF-e com wrapper
Invoice e todos os campos obrigatórios
- Valida o formato da chave de acesso (44 dígitos) antes de montar a chamada
- Usa o endpoint correto
POST /orders/:order_id/invoices com o order_id na URL
- 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 configuradoorder_id do pedido já existente na Tray- Dados da NF-e emitida pelo sistema fiscal (número, série, chave de acesso)
