Limites, idempotência, paginação e versões

As regras que valem para todos os endpoints.

Limite de requisições

Cada token tem um balde de 50 requisições que recarrega 5 por segundo. Um lote de até 100 itens conta como uma requisição. Acima disso, a resposta é 429 rate_limited com Retry-After.

Cabeçalho	Descrição
`RateLimit-Limit`	Tamanho do balde.
`RateLimit-Remaining`	Requisições disponíveis agora.
`RateLimit-Reset`	Segundos até o balde encher de novo.
`Retry-After`	Em `429`: segundos de espera antes de tentar de novo.

http

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 10
Retry-After: 1
X-Request-Id: req_9Qa1zE5vB7mN2x

Para cargas grandes, use lotes e updated_since. Evite polling mais de uma vez por minuto.

Idempotência

Os POST marcados na referência aceitam o cabeçalho Idempotency-Key (use um UUID por operação). A chave vale por 24 horas, por token:

Mesma chave e mesma requisição: devolvemos a resposta original, sem repetir o efeito.
Mesma chave com corpo diferente: 422 idempotency_key_reuse.
Em timeout ou erro de rede, reenvie com a mesma chave.
Só respostas de sucesso (2xx) ficam guardadas. Depois de corrigir a causa de um erro (por exemplo, 409 invoice_issuer_mismatch), reenvie com a mesma chave: a requisição roda de novo.

http

Idempotency-Key: 6c1f2a9e-5b7d-4e3a-9f10-2d8c4b6a7e51

Também há chaves naturais: a NF-e é única pela chave de acesso, o acknowledge por app e pedido, e o envio por pedido e código de rastreio.

Paginação

Listas usam cursor. A resposta é { data, next_cursor }; envie cursor para a próxima página até next_cursor vir null. limit vai de 1 a 100 (padrão 50). Cursores são opacos: não os monte nem os guarde por muito tempo.

bash

# First page
curl "https://api.tfshop.cloud/v1/orders?updated_since=2026-10-29T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

# → { "data": [ … ], "next_cursor": "eyJ1Ijoi…" }

# Next page: same filters + the cursor, until next_cursor is null
curl "https://api.tfshop.cloud/v1/orders?updated_since=2026-10-29T00:00:00Z&limit=100&cursor=eyJ1Ijoi…" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

Sincronização incremental

Guarde o maior updated_at que você processou e use-o como updated_since na próxima rodada, com alguns segundos de folga. Os resultados vêm em ordem de updated_at e id.

Versões

A versão vai na URL: /v1.
Mudanças compatíveis não mudam a versão: novos campos, endpoints, eventos e valores de enum. Ignore campos desconhecidos e aceite valores novos.
Mudanças incompatíveis só saem numa nova versão (/v2), com pelo menos 12 meses de convivência entre as duas.
O que for descontinuado responde com os cabeçalhos Deprecation (RFC 9745) e Sunset (RFC 8594), com a data de desligamento. Tudo é anunciado no changelog.

http

HTTP/1.1 200 OK
Deprecation: @1793491200
Sunset: Sun, 31 Oct 2027 23:59:59 GMT
Link: <https://developers.tfshop.cloud/changelog>; rel="deprecation"

Limite de requisições

Cada token tem um balde de 50 requisições que recarrega 5 por segundo. Um lote de até 100 itens conta como uma requisição. Acima disso, a resposta é 429 rate_limited com Retry-After.

Cabeçalho	Descrição
`RateLimit-Limit`	Tamanho do balde.
`RateLimit-Remaining`	Requisições disponíveis agora.
`RateLimit-Reset`	Segundos até o balde encher de novo.
`Retry-After`	Em `429`: segundos de espera antes de tentar de novo.

http

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Limit: 50
RateLimit-Remaining: 0
RateLimit-Reset: 10
Retry-After: 1
X-Request-Id: req_9Qa1zE5vB7mN2x

Para cargas grandes, use lotes e updated_since. Evite polling mais de uma vez por minuto.

Idempotência

Os POST marcados na referência aceitam o cabeçalho Idempotency-Key (use um UUID por operação). A chave vale por 24 horas, por token:

Mesma chave e mesma requisição: devolvemos a resposta original, sem repetir o efeito.
Mesma chave com corpo diferente: 422 idempotency_key_reuse.
Em timeout ou erro de rede, reenvie com a mesma chave.
Só respostas de sucesso (2xx) ficam guardadas. Depois de corrigir a causa de um erro (por exemplo, 409 invoice_issuer_mismatch), reenvie com a mesma chave: a requisição roda de novo.

http

Idempotency-Key: 6c1f2a9e-5b7d-4e3a-9f10-2d8c4b6a7e51

Também há chaves naturais: a NF-e é única pela chave de acesso, o acknowledge por app e pedido, e o envio por pedido e código de rastreio.

Paginação

bash

# First page
curl "https://api.tfshop.cloud/v1/orders?updated_since=2026-10-29T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

# → { "data": [ … ], "next_cursor": "eyJ1Ijoi…" }

# Next page: same filters + the cursor, until next_cursor is null
curl "https://api.tfshop.cloud/v1/orders?updated_since=2026-10-29T00:00:00Z&limit=100&cursor=eyJ1Ijoi…" \
  -H "Authorization: Bearer $TFSHOP_TOKEN"

Versões

A versão vai na URL: /v1.
Mudanças compatíveis não mudam a versão: novos campos, endpoints, eventos e valores de enum. Ignore campos desconhecidos e aceite valores novos.
Mudanças incompatíveis só saem numa nova versão (/v2), com pelo menos 12 meses de convivência entre as duas.
O que for descontinuado responde com os cabeçalhos Deprecation (RFC 9745) e Sunset (RFC 8594), com a data de desligamento. Tudo é anunciado no changelog.

http

HTTP/1.1 200 OK
Deprecation: @1793491200
Sunset: Sun, 31 Oct 2027 23:59:59 GMT
Link: <https://developers.tfshop.cloud/changelog>; rel="deprecation"