Referência da API

Gerada do OpenAPI 1.3.0: 31 endpoints em https://convertaja.com.br/v1. Abra Testar agora em qualquer endpoint para fazer a chamada daqui mesmo.

Chave de teste (cj_test_…, não gasta créditos, 20 chamadas/dia)

Entre e crie uma chave de teste grátis em segundos. O console aceita só chaves de teste; a chave fica nesta aba e vai só para a API. Em produção, chame a API do seu servidor.

Conta

GET `/v1/me` #

Conta, plano e créditos. Mostra a conta dona da chave, o plano, os créditos (franquia, pacotes, saldo) e os limites.

Custo: grátis (não consome créditos)

Resposta 200: Me

Campo	Tipo	Descrição
`account`	object
`key`	object
`plan`	object
`credits`	object
`limits`	object

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

GET `/v1/usage` #

Uso por dia. Créditos e chamadas por dia e por endpoint. Padrão: últimos 30 dias. Máximo de 366 dias.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`from`	query	Data inicial AAAA-MM-DD.
`to`	query	Data final AAAA-MM-DD (padrão: hoje).

Resposta 200: Usage

Campo	Tipo	Descrição
`from`	string
`to`	string
`totals`	object
`data`	array de object

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

from (query)to (query)

Ferramentas de arquivo

GET `/v1/tools` #

Listar ferramentas. Todas as ferramentas de arquivo com extensões aceitas, opções em JSON Schema e custo em créditos.

Custo: grátis (não consome créditos)

Resposta 200: object

Campo	Tipo	Descrição
`object`	string
`count`	integer
`data`	array de Tool

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

GET `/v1/tools/{toolId}` #

Detalhes de uma ferramenta. Uma ferramenta, com o JSON Schema das opções.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`toolId` obrigatório	caminho	Id da ferramenta (ex.: unir-pdf).

Resposta 200: Tool

Campo	Tipo	Descrição
`id`	string	Id usado em POST /v1/tools/{id}.
`operation`	string	Operação interna.
`name`	string	Nome.
`description`	string	Descrição.
`category`	string	Categoria.
`accepted_extensions`	array de string
`multiple`	boolean	Aceita vários arquivos.
`min_files`	integer	Mínimo de arquivos.
`max_files`	integer \| null
`optional_files`	boolean	Arquivos opcionais (ex.: Site para PDF com url).
`extra_files`	array de object
`options_schema`	object	JSON Schema das opções.
`fixed_options`	object
`heavy`	boolean	Ferramenta pesada.
`kind`	string light, heavy, video	light \| heavy \| video
`credits_per_file`	integer	Créditos por arquivo enviado.
`docs_url`	string

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

toolId (caminho)

POST `/v1/tools/{toolId}` #

Criar tarefa. Envia os arquivos e cria a tarefa. Responde 202 com a tarefa; use ?wait=true para esperar até 60 s pelo resultado.

Custo: 1, 5 ou 10 por arquivo crédito(s) · opções de cada ferramenta

Parâmetro	Onde	Descrição
`toolId` obrigatório	caminho	Id da ferramenta.
`wait`	query	true (até 60 s) ou número de segundos (1–60).
`webhook_url`	query	URL HTTPS que recebe o aviso de conclusão.
`Idempotency-Key`	cabeçalho	Chave única da operação (ex.: um UUID). Repetir o mesmo pedido com a mesma chave em até 24 h devolve a resposta original, sem novo débito (cabeçalho Idempotent-Replayed: true). Mesma chave com outro pedido: 409 idempotency_key_reused.

Resposta 200: Job

Campo	Tipo	Descrição
`id` obrigatório	string	Identificador da tarefa.
`tool`	string	Id da ferramenta.
`operation`	string	Operação interna.
`status` obrigatório	string queued, running, done, error	Situação.
`progress`	integer	0 a 100.
`message`	string	Mensagem de progresso ou de erro.
`created_at`	string	Criação (ISO 8601).
`finished_at`	string \| null
`expires_at`	string	Quando os arquivos são apagados (1 hora após a criação).
`credits_charged`	integer	Créditos debitados.
`credits_refunded`	integer	Créditos devolvidos (tarefa com erro).
`test`	boolean	Criada com chave de teste.
`outputs`	array de JobOutput
`download_url`	string	Baixa tudo (um arquivo ou ZIP).
`info`	string	Informação extra da ferramenta (ex.: tamanho antes/depois).
`text`	string	Resultado em texto, quando a ferramenta gera texto (ex.: ZPL do pdf-para-zpl, até 256 KB).
`error`	object
`files_available`	boolean	Os arquivos ainda podem ser baixados (até 1 hora após a criação, ou até DELETE).
`files_deleted_at`	string \| null	Quando os arquivos foram apagados com DELETE /v1/jobs/{id}.
`deleted`	boolean	Presente (true) na resposta do DELETE.

Erros: 400 · 401 · 402 · 409 · 413 · 415 · 429 — veja a tabela de códigos.

Testar agora

toolId (caminho)wait (query)webhook_url (query)Arquivosoptions (JSON) Enviar Idempotency-Key aleatória

Tarefas

GET `/v1/jobs` #

Listar tarefas. Tarefas da conta, da mais recente para a mais antiga (guardadas por 90 dias; os arquivos, por 1 hora). Pagine com next_cursor em starting_after.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`limit`	query	1 a 100 (padrão 20).
`starting_after`	query	Id da última tarefa da página anterior (next_cursor). cursor também é aceito.
`status`	query	queued, running, done ou error (vários separados por vírgula).
`tool`	query	Id da ferramenta (ex.: comprimir-pdf).
`created_after`	query	Criadas depois de (ISO 8601 ou Unix em segundos; data sem hora = 00:00 de Brasília).
`created_before`	query	Criadas antes de (mesmo formato).

Resposta 200: JobList

Campo	Tipo	Descrição
`object`	string
`count`	integer	Itens nesta página.
`has_more`	boolean	Há mais páginas.
`next_cursor`	string \| null	Id da última tarefa da página; passe em starting_after.
`data`	array de Job

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

limit (query)starting_after (query)status (query)tool (query)created_after (query)created_before (query)

GET `/v1/jobs/{id}` #

Consultar tarefa. Situação, progresso e arquivos gerados. Só a conta que criou a tarefa consegue consultar. Depois de 1 hora a tarefa continua consultável (90 dias), com files_available: false.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id da tarefa.

Resposta 200: Job

Campo	Tipo	Descrição
`id` obrigatório	string	Identificador da tarefa.
`tool`	string	Id da ferramenta.
`operation`	string	Operação interna.
`status` obrigatório	string queued, running, done, error	Situação.
`progress`	integer	0 a 100.
`message`	string	Mensagem de progresso ou de erro.
`created_at`	string	Criação (ISO 8601).
`finished_at`	string \| null
`expires_at`	string	Quando os arquivos são apagados (1 hora após a criação).
`credits_charged`	integer	Créditos debitados.
`credits_refunded`	integer	Créditos devolvidos (tarefa com erro).
`test`	boolean	Criada com chave de teste.
`outputs`	array de JobOutput
`download_url`	string	Baixa tudo (um arquivo ou ZIP).
`info`	string	Informação extra da ferramenta (ex.: tamanho antes/depois).
`text`	string	Resultado em texto, quando a ferramenta gera texto (ex.: ZPL do pdf-para-zpl, até 256 KB).
`error`	object
`files_available`	boolean	Os arquivos ainda podem ser baixados (até 1 hora após a criação, ou até DELETE).
`files_deleted_at`	string \| null	Quando os arquivos foram apagados com DELETE /v1/jobs/{id}.
`deleted`	boolean	Presente (true) na resposta do DELETE.

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)

POST `/v1/jobs/{id}/delete` #

Apagar arquivos da tarefa. Apaga os arquivos gerados antes de 1 hora (LGPD, dados sensíveis). A tarefa continua listada, com files_available: false. Também aceito como DELETE /v1/jobs/{id}. Tarefa em andamento: 409 job_running (não há cancelamento no meio).

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id da tarefa.

Resposta 200: Job

Campo	Tipo	Descrição
`id` obrigatório	string	Identificador da tarefa.
`tool`	string	Id da ferramenta.
`operation`	string	Operação interna.
`status` obrigatório	string queued, running, done, error	Situação.
`progress`	integer	0 a 100.
`message`	string	Mensagem de progresso ou de erro.
`created_at`	string	Criação (ISO 8601).
`finished_at`	string \| null
`expires_at`	string	Quando os arquivos são apagados (1 hora após a criação).
`credits_charged`	integer	Créditos debitados.
`credits_refunded`	integer	Créditos devolvidos (tarefa com erro).
`test`	boolean	Criada com chave de teste.
`outputs`	array de JobOutput
`download_url`	string	Baixa tudo (um arquivo ou ZIP).
`info`	string	Informação extra da ferramenta (ex.: tamanho antes/depois).
`text`	string	Resultado em texto, quando a ferramenta gera texto (ex.: ZPL do pdf-para-zpl, até 256 KB).
`error`	object
`files_available`	boolean	Os arquivos ainda podem ser baixados (até 1 hora após a criação, ou até DELETE).
`files_deleted_at`	string \| null	Quando os arquivos foram apagados com DELETE /v1/jobs/{id}.
`deleted`	boolean	Presente (true) na resposta do DELETE.

Erros: 401 · 404 · 409 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)

GET `/v1/jobs/{id}/files/{index}` #

Baixar um arquivo. Baixa o arquivo gerado na posição index.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id da tarefa.
`index` obrigatório	caminho	Posição do arquivo (0, 1, …).

Resposta 200: arquivo (application/octet-stream).

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)index (caminho)

GET `/v1/jobs/{id}/download` #

Baixar tudo. Baixa o arquivo gerado ou, se houver vários, um ZIP com todos.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id da tarefa.

Resposta 200: arquivo (application/octet-stream).

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)

Webhooks

POST `/v1/webhooks/test` #

Testar webhook. Envia um evento webhook.test assinado (mesmo formato e cabeçalhos dos eventos reais) para a URL e devolve o que o receptor respondeu. Uma tentativa, sem novas tentativas. Use para conferir a verificação da assinatura antes de ir para produção.

Custo: grátis (não consome créditos)

Corpo (JSON)

Campo	Tipo	Descrição
`url` obrigatório	string	URL HTTPS pública do seu receptor.

Resposta 200: WebhookTest

Campo	Tipo	Descrição
`object`	string
`url`	string
`event`	string
`delivery_id`	string	Mesmo valor de X-Convertaja-Delivery.
`delivered`	boolean	O receptor respondeu 2xx.
`status`	integer \| null	Status HTTP devolvido pelo receptor.
`error`	string \| null

Erros: 400 · 401 · 402 · 429 — veja a tabela de códigos.

Testar agora

Corpo (JSON)

Assinatura eletrônica

POST `/v1/esign/envelopes` #

Criar envelope. Sobe o PDF, define signatários e campos e (por padrão) envia os convites por e-mail. Envie multipart/form-data com "file" (PDF até 20 MB e 100 páginas) e "data" (JSON com os campos abaixo), ou JSON com "file": { "base64": "…", "name": "…" } ou { "url": "https://…" } mais os mesmos campos. Responde 201 com o envelope. Além dos créditos, vale a cota mensal de documentos do plano do site (Grátis 3, Pro 30, Empresas 200); acima dela, 402 esign_quota.

Custo: 20 quando enviado (rascunho: 0) crédito(s)

Parâmetro	Onde	Descrição
`Idempotency-Key`	cabeçalho	Chave única da operação (ex.: um UUID). Repetir o mesmo pedido com a mesma chave em até 24 h devolve a resposta original, sem novo débito (cabeçalho Idempotent-Replayed: true). Mesma chave com outro pedido: 409 idempotency_key_reused.

Corpo (JSON)

Campo	Tipo	Descrição
`file` obrigatório	object \| object
`name`	string	Nome do documento (padrão: nome do arquivo).
`signers` obrigatório	array de object	Até 10 pessoas.
`fields`	array de object	Onde cada pessoa assina (coordenadas relativas, origem no canto superior esquerdo).
`message`	string	Mensagem no convite (até 1.000 caracteres).
`expires_at`	string	Prazo: ISO 8601 ou AAAA-MM-DD (padrão 30 dias, máximo 90).
`sequential`	boolean	Um de cada vez, na ordem de signers.
`send`	boolean	Envia na hora (cobra 20 créditos). false = rascunho grátis.
`return_links`	boolean	Devolve signers[].sign_url (para enviar o link você mesmo). Em rascunho (send: false) os links ainda não existem: sign_url vem null e o pedido fica guardado; os links saem na resposta de POST …/send.
`webhook_url`	string	URL HTTPS que recebe esign.envelope.completed \| refused \| expired \| canceled.

Resposta 201: Envelope

Campo	Tipo	Descrição
`id` obrigatório	string	Id do envelope (XXXX-XXXX-XXXX-XXXX).
`object`	string
`name`	string	Nome do documento.
`file_name`	string \| null
`status` obrigatório	string draft, pending, completed, refused, expired, canceled	Situação.
`status_label`	string	Situação em português.
`source`	string	api \| web
`sequential`	boolean	Assinatura em ordem.
`message`	string \| null
`pages`	integer	Páginas.
`signed_count`	integer
`signer_count`	integer
`created_at`	string
`updated_at`	string
`sent_at`	string \| null
`completed_at`	string \| null
`closed_at`	string \| null
`expires_at`	string \| null
`purge_at`	string \| null	Quando os arquivos são apagados.
`original_sha256`	string	Hash do PDF enviado.
`final_sha256`	string \| null	Hash do PDF final (verificável em verify_url).
`verify_url`	string \| null
`signers`	array de EnvelopeSigner
`fields`	array de object
`files`	object \| null
`credits_charged`	integer	Créditos cobrados (20 no envio).
`webhook_url`	string \| null
`url`	string
`links_available`	boolean	Presente quando os links foram pedidos: false em rascunho (os links saem no envio).
`events`	array de object	Trilha de auditoria (com ?events=true).

Erros: 400 · 401 · 402 · 409 · 413 · 415 · 422 · 429 — veja a tabela de códigos.

Testar agora

Corpo (JSON) Enviar Idempotency-Key aleatória

GET `/v1/esign/envelopes` #

Listar envelopes. Envelopes da conta (criados pela API ou pelo site), do mais recente para o mais antigo. Pagine com next_cursor (ou offset).

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`limit`	query	1 a 100 (padrão 20).
`cursor`	query	next_cursor da página anterior.
`offset`	query	Alternativa ao cursor: pula N envelopes.
`status`	query	draft, pending, completed, refused, expired ou canceled.

Resposta 200: EnvelopeList

Campo	Tipo	Descrição
`object`	string
`count`	integer
`has_more`	boolean
`next_cursor`	string \| null
`data`	array de Envelope

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

limit (query)cursor (query)offset (query)status (query)

GET `/v1/esign/envelopes/{id}` #

Consultar envelope. Situação do envelope e de cada signatário (convidado, abriu, confirmou o código, assinou ou recusou, com horários). Com ?events=true, inclui a trilha de auditoria.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).
`events`	query	true para incluir os eventos (IP, porta, dispositivo, horário).
`links`	query	true para incluir signers[].sign_url (links pessoais de assinatura; só depois do envio).

Resposta 200: Envelope

Campo	Tipo	Descrição
`id` obrigatório	string	Id do envelope (XXXX-XXXX-XXXX-XXXX).
`object`	string
`name`	string	Nome do documento.
`file_name`	string \| null
`status` obrigatório	string draft, pending, completed, refused, expired, canceled	Situação.
`status_label`	string	Situação em português.
`source`	string	api \| web
`sequential`	boolean	Assinatura em ordem.
`message`	string \| null
`pages`	integer	Páginas.
`signed_count`	integer
`signer_count`	integer
`created_at`	string
`updated_at`	string
`sent_at`	string \| null
`completed_at`	string \| null
`closed_at`	string \| null
`expires_at`	string \| null
`purge_at`	string \| null	Quando os arquivos são apagados.
`original_sha256`	string	Hash do PDF enviado.
`final_sha256`	string \| null	Hash do PDF final (verificável em verify_url).
`verify_url`	string \| null
`signers`	array de EnvelopeSigner
`fields`	array de object
`files`	object \| null
`credits_charged`	integer	Créditos cobrados (20 no envio).
`webhook_url`	string \| null
`url`	string
`links_available`	boolean	Presente quando os links foram pedidos: false em rascunho (os links saem no envio).
`events`	array de object	Trilha de auditoria (com ?events=true).

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)events (query)links (query)

POST `/v1/esign/envelopes/{id}/send` #

Enviar rascunho. Envia um envelope criado com send: false. Cobra 20 créditos (estornados se o envio falhar) e conta na cota mensal do plano. Devolve signers[].sign_url se o rascunho foi criado com return_links: true ou se você mandar {"return_links": true} (ou ?return_links=true).

Custo: 20 crédito(s)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).
`return_links`	query	true para devolver os links de assinatura (também aceito no corpo JSON).
`Idempotency-Key`	cabeçalho	Chave única da operação (ex.: um UUID). Repetir o mesmo pedido com a mesma chave em até 24 h devolve a resposta original, sem novo débito (cabeçalho Idempotent-Replayed: true). Mesma chave com outro pedido: 409 idempotency_key_reused.

Resposta 200: Envelope

Campo	Tipo	Descrição
`id` obrigatório	string	Id do envelope (XXXX-XXXX-XXXX-XXXX).
`object`	string
`name`	string	Nome do documento.
`file_name`	string \| null
`status` obrigatório	string draft, pending, completed, refused, expired, canceled	Situação.
`status_label`	string	Situação em português.
`source`	string	api \| web
`sequential`	boolean	Assinatura em ordem.
`message`	string \| null
`pages`	integer	Páginas.
`signed_count`	integer
`signer_count`	integer
`created_at`	string
`updated_at`	string
`sent_at`	string \| null
`completed_at`	string \| null
`closed_at`	string \| null
`expires_at`	string \| null
`purge_at`	string \| null	Quando os arquivos são apagados.
`original_sha256`	string	Hash do PDF enviado.
`final_sha256`	string \| null	Hash do PDF final (verificável em verify_url).
`verify_url`	string \| null
`signers`	array de EnvelopeSigner
`fields`	array de object
`files`	object \| null
`credits_charged`	integer	Créditos cobrados (20 no envio).
`webhook_url`	string \| null
`url`	string
`links_available`	boolean	Presente quando os links foram pedidos: false em rascunho (os links saem no envio).
`events`	array de object	Trilha de auditoria (com ?events=true).

Erros: 401 · 402 · 404 · 409 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)return_links (query) Enviar Idempotency-Key aleatória

POST `/v1/esign/envelopes/{id}/remind` #

Lembrar quem falta. Reenvia o convite para quem está com a vez e ainda não assinou. No máximo um lembrete a cada 30 minutos por pessoa (429 reminder_too_soon).

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).

Resposta 200: EnvelopeReminder

Campo	Tipo	Descrição
`id`	string	Id do envelope.
`reminded`	integer	Quantas pessoas receberam o lembrete.

Erros: 401 · 404 · 409 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)

POST `/v1/esign/envelopes/{id}/cancel` #

Cancelar envelope. Cancela um rascunho ou um envelope aguardando assinaturas e avisa quem estava com a vez. Os créditos do envio não são devolvidos.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).

Resposta 200: Envelope

Campo	Tipo	Descrição
`id` obrigatório	string	Id do envelope (XXXX-XXXX-XXXX-XXXX).
`object`	string
`name`	string	Nome do documento.
`file_name`	string \| null
`status` obrigatório	string draft, pending, completed, refused, expired, canceled	Situação.
`status_label`	string	Situação em português.
`source`	string	api \| web
`sequential`	boolean	Assinatura em ordem.
`message`	string \| null
`pages`	integer	Páginas.
`signed_count`	integer
`signer_count`	integer
`created_at`	string
`updated_at`	string
`sent_at`	string \| null
`completed_at`	string \| null
`closed_at`	string \| null
`expires_at`	string \| null
`purge_at`	string \| null	Quando os arquivos são apagados.
`original_sha256`	string	Hash do PDF enviado.
`final_sha256`	string \| null	Hash do PDF final (verificável em verify_url).
`verify_url`	string \| null
`signers`	array de EnvelopeSigner
`fields`	array de object
`files`	object \| null
`credits_charged`	integer	Créditos cobrados (20 no envio).
`webhook_url`	string \| null
`url`	string
`links_available`	boolean	Presente quando os links foram pedidos: false em rascunho (os links saem no envio).
`events`	array de object	Trilha de auditoria (com ?events=true).

Erros: 401 · 404 · 409 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)

POST `/v1/esign/envelopes/{id}/delete` #

Excluir envelope. Apaga o envelope, os arquivos e a trilha de auditoria, em qualquer situação. Também aceito como DELETE /v1/esign/envelopes/{id}.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).

Resposta 200: EnvelopeDeleted

Campo	Tipo	Descrição
`id`	string	Id do envelope.
`object`	string
`deleted`	boolean

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)

GET `/v1/esign/envelopes/{id}/files/final` #

Baixar PDF assinado. PDF final com as assinaturas aplicadas e o relatório de assinaturas anexado (application/pdf). Só depois que todos assinam (409 envelope_not_completed antes disso). Fica guardado 90 dias.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).

Resposta 200: arquivo (application/pdf).

Erros: 401 · 404 · 409 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)

GET `/v1/esign/envelopes/{id}/files/audit` #

Baixar relatório de assinaturas. Só o relatório de assinaturas (evidências: IP/porta, dispositivo, horários, hash SHA-256 e QR Code de verificação), em PDF.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id do envelope (XXXX-XXXX-XXXX-XXXX).

Resposta 200: arquivo (application/pdf).

Erros: 401 · 404 · 409 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)

Central de Expedição

POST `/v1/expedicao/lotes` #

Criar lote de expedição. Recebe os PDFs das etiquetas de envio (Mercado Livre, Shopee, Amazon, Correios, Magalu…) em "labels" e, opcionalmente, os XMLs (ou um ZIP) das NF-e em "xmls". Recorta as etiquetas em 10×15, associa cada etiqueta à nota (pelo número da NF, rastreio ou destinatário) e gera os PDFs prontos para a térmica, intercalando etiqueta e DANFE simplificado quando intercalar=true (padrão quando há XMLs). Custa 2 créditos por pedido novo no mês: o mesmo rastreio processado de novo no mesmo mês não é cobrado. Sem saldo para o lote inteiro, nada é processado (402). Use ?wait=true para esperar até 60 s.

Custo: 2 por pedido novo no mês crédito(s)

Parâmetro	Onde	Descrição
`wait`	query	true (até 60 s) ou número de segundos (1–60).
`Idempotency-Key`	cabeçalho	Chave única da operação (ex.: um UUID). Repetir o mesmo pedido com a mesma chave em até 24 h devolve a resposta original, sem novo débito (cabeçalho Idempotent-Replayed: true). Mesma chave com outro pedido: 409 idempotency_key_reused.

Resposta 202: Lote

Campo	Tipo	Descrição
`id`	string	Id do lote.
`object`	string
`status`	string running, done, error	Situação.
`progress`	integer	0 a 100.
`message`	string \| null
`orders`	integer	Pedidos (etiquetas) no lote.
`new_orders`	integer	Pedidos ainda não processados no mês (são os cobrados).
`credits_charged`	integer	Créditos debitados.
`created_at`	string
`finished_at`	string \| null
`files_expire_at`	string \| null
`outputs`	array de object
`download_url`	string	ZIP com todos os PDFs.
`conference_url`	string	Página de conferência dos pedidos (sem login).
`summary`	object	Resumo: pedidos por marketplace e transportadora, etiquetas sem nota, notas sem etiqueta, lista de pedidos.
`error`	object

Erros: 400 · 401 · 402 · 409 · 413 · 415 · 422 · 429 — veja a tabela de códigos.

Testar agora

wait (query)labels Enviar Idempotency-Key aleatória

GET `/v1/expedicao/lotes/{id}` #

Consultar lote. Situação, resumo (pedidos por marketplace e transportadora, etiquetas sem nota) e os PDFs gerados. Histórico por 30 dias; arquivos por 7 dias.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id do lote.

Resposta 200: Lote

Campo	Tipo	Descrição
`id`	string	Id do lote.
`object`	string
`status`	string running, done, error	Situação.
`progress`	integer	0 a 100.
`message`	string \| null
`orders`	integer	Pedidos (etiquetas) no lote.
`new_orders`	integer	Pedidos ainda não processados no mês (são os cobrados).
`credits_charged`	integer	Créditos debitados.
`created_at`	string
`finished_at`	string \| null
`files_expire_at`	string \| null
`outputs`	array de object
`download_url`	string	ZIP com todos os PDFs.
`conference_url`	string	Página de conferência dos pedidos (sem login).
`summary`	object	Resumo: pedidos por marketplace e transportadora, etiquetas sem nota, notas sem etiqueta, lista de pedidos.
`error`	object

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)

GET `/v1/expedicao/lotes/{id}/files/{name}` #

Baixar um PDF do lote. Baixa um dos PDFs do lote (nome em outputs[].name).

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id do lote.
`name` obrigatório	caminho	Nome do arquivo.

Resposta 200: arquivo (application/pdf).

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)name (caminho)

GET `/v1/expedicao/lotes/{id}/download` #

Baixar o lote (ZIP). ZIP com todos os PDFs do lote. 409 lote_not_ready antes de terminar.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`id` obrigatório	caminho	Id do lote.

Resposta 200: arquivo (application/zip).

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

id (caminho)

Dados

GET `/v1/cnpj/{cnpj}` #

Consultar CNPJ. Razão social, situação, endereço, CNAEs e Simples Nacional, da base pública da Receita Federal. Aceita o CNPJ alfanumérico. Sem quadro de sócios (LGPD). Grátis: vale só o limite de requisições por minuto.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`cnpj` obrigatório	caminho	CNPJ com ou sem pontuação (numérico ou alfanumérico).

Resposta 200: Company

Campo	Tipo	Descrição
`cnpj`	string
`razaoSocial`	string
`nomeFantasia`	string
`situacao`	string
`abertura`	string
`porte`	string
`naturezaJuridica`	string
`cnaePrincipal`	object
`cnaesSecundarios`	array de object
`endereco`	object
`telefone`	string
`email`	string
`capitalSocial`	number \| null
`simples`	object
`cached`	boolean	Veio do cache (24 h).

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

cnpj (caminho)

GET `/v1/cep/{cep}` #

Consultar CEP. Logradouro, bairro, cidade e UF. Fonte: BrasilAPI, com ViaCEP de reserva. Grátis: vale só o limite de requisições por minuto.

Custo: grátis (não consome créditos)

Parâmetro	Onde	Descrição
`cep` obrigatório	caminho	CEP com 8 números.

Resposta 200: Address

Campo	Tipo	Descrição
`cep`	string
`logradouro`	string
`bairro`	string
`cidade`	string
`uf`	string
`cached`	boolean

Erros: 401 · 404 · 429 — veja a tabela de códigos.

Testar agora

cep (caminho)

POST `/v1/validate` #

Validar documentos. Confere os dígitos verificadores de CPF, CNPJ (inclusive alfanumérico), CNH, PIS/PASEP, título de eleitor, RENAVAM e CNS. Sem tipo, deduz pelo tamanho.

Custo: 1 (lote: 1 a cada 50) crédito(s)

Parâmetro	Onde	Descrição
`Idempotency-Key`	cabeçalho	Chave única da operação (ex.: um UUID). Repetir o mesmo pedido com a mesma chave em até 24 h devolve a resposta original, sem novo débito (cabeçalho Idempotent-Replayed: true). Mesma chave com outro pedido: 409 idempotency_key_reused.

Corpo (JSON)

Campo	Tipo	Descrição
`type`	string cpf, cnpj, cnh, pis, titulo, renavam, cns	Tipo do documento (opcional).
`value`	string	Um documento.
`values`	array de string	Lista de documentos (até 1.000).

Resposta 200: ValidationResult

Campo	Tipo	Descrição
`value`	string	Valor recebido.
`type`	string \| null cpf, cnpj, cnh, pis, titulo, renavam, cns, null
`type_label`	string
`valid`	boolean	Dígitos verificadores conferem.
`normalized`	string	Só os caracteres significativos.
`formatted`	string \| null
`alphanumeric`	boolean	CNPJ no novo formato alfanumérico.
`candidates`	array de string	Tipos possíveis quando o tipo não foi informado.

Erros: 400 · 401 · 402 · 409 · 429 — veja a tabela de códigos.

Testar agora

Corpo (JSON) Enviar Idempotency-Key aleatória

POST `/v1/boleto/parse` #

Ler boleto. Linha digitável (47 bancário, 48 arrecadação) ou código de barras (44) → confere os DVs, converte e mostra banco, valor e vencimento (com o novo fator de vencimento de 22/02/2025).

Custo: 1 crédito(s)

Parâmetro	Onde	Descrição
`Idempotency-Key`	cabeçalho	Chave única da operação (ex.: um UUID). Repetir o mesmo pedido com a mesma chave em até 24 h devolve a resposta original, sem novo débito (cabeçalho Idempotent-Replayed: true). Mesma chave com outro pedido: 409 idempotency_key_reused.

Corpo (JSON)

Campo	Tipo	Descrição
`code` obrigatório	string	Linha digitável ou código de barras, com ou sem pontuação.

Resposta 200: Boleto

Campo	Tipo	Descrição
`tipo`	string	bancario \| arrecadacao
`valido`	boolean
`codigo_barras`	string	44 dígitos.
`linha_digitavel`	string	47 ou 48 dígitos.
`linha_digitavel_formatada`	string
`banco`	object
`segmento`	object
`valor`	number \| null
`vencimento`	string \| null
`fator_vencimento`	integer \| null

Erros: 400 · 401 · 402 · 409 · 429 — veja a tabela de códigos.

Testar agora

Corpo (JSON) Enviar Idempotency-Key aleatória

POST `/v1/pix/brcode` #

Pix copia e cola (BR Code). Gera o BR Code estático (padrão do Banco Central) e, conforme format, o QR Code em SVG, PNG ou uma folha em PDF. format: json (só o copia e cola), svg, png, both (padrão: SVG e PNG) ou pdf (folha 10×15 cm com QR, nome, cidade, valor e copia e cola, em pdf_base64).

Custo: 1 crédito(s)

Parâmetro	Onde	Descrição
`Idempotency-Key`	cabeçalho	Chave única da operação (ex.: um UUID). Repetir o mesmo pedido com a mesma chave em até 24 h devolve a resposta original, sem novo débito (cabeçalho Idempotent-Replayed: true). Mesma chave com outro pedido: 409 idempotency_key_reused.

Corpo (JSON)

Campo	Tipo	Descrição
`key` obrigatório	string	Chave Pix: CPF, CNPJ, e-mail, telefone +55 ou aleatória.
`name` obrigatório	string	Nome de quem recebe (até 25).
`city` obrigatório	string	Cidade (até 15).
`amount`	number	Valor em reais (opcional).
`txid`	string	Identificador (até 25 letras/números). Padrão ***.
`description`	string	Mensagem (opcional).
`format`	string json, svg, png, both, pdf	json, svg, png, both (padrão) ou pdf.
`module_size`	integer	Pixels por módulo do QR (1–40).
`margin`	integer	Margem em módulos (0–20).
`color`	string	#RRGGBB
`background`	string	#RRGGBB ou transparent

Resposta 200: Pix

Campo	Tipo	Descrição
`payload`	string	Pix copia e cola (BR Code).
`key`	string	Chave normalizada.
`key_type`	string	cpf \| cnpj \| email \| telefone \| aleatoria
`amount`	number \| null
`txid`	string
`format`	string json, svg, png, both, pdf	Formato pedido.
`qr_width`	integer	Largura do QR (px).
`qr_height`	integer	Altura do QR (px).
`qr_svg`	string	QR em SVG (format svg ou both).
`qr_png_base64`	string	QR em PNG, base64 (format png ou both).
`pdf_base64`	string	Folha 10×15 cm com QR, nome, cidade, valor e copia e cola (format pdf).

Erros: 400 · 401 · 402 · 409 · 429 — veja a tabela de códigos.

Testar agora

Corpo (JSON) Enviar Idempotency-Key aleatória

POST `/v1/qrcode` #

Gerar QR Code. QR Code de qualquer texto ou link, em SVG e/ou PNG.

Custo: 1 crédito(s)

Parâmetro	Onde	Descrição
`Idempotency-Key`	cabeçalho	Chave única da operação (ex.: um UUID). Repetir o mesmo pedido com a mesma chave em até 24 h devolve a resposta original, sem novo débito (cabeçalho Idempotent-Replayed: true). Mesma chave com outro pedido: 409 idempotency_key_reused.

Corpo (JSON)

Campo	Tipo	Descrição
`text` obrigatório	string	Conteúdo (até 2.900 caracteres).
`format`	string svg, png, both	svg (padrão), png ou both.
`ecc`	string L, M, Q, H	Correção de erros.
`module_size`	integer	Pixels por módulo (1–40).
`margin`	integer	Margem em módulos (0–20).
`color`	string	#RRGGBB
`background`	string	#RRGGBB ou transparent

Resposta 200: Image

Campo	Tipo	Descrição
`width`	number	Largura (px).
`height`	number	Altura (px).
`svg`	string	SVG (format svg ou both).
`png_base64`	string	PNG em base64 (format png ou both).

Erros: 400 · 401 · 402 · 409 · 429 — veja a tabela de códigos.

Testar agora

Corpo (JSON) Enviar Idempotency-Key aleatória

POST `/v1/barcode` #

Gerar código de barras. Code 128, EAN-13, EAN-8, UPC-A, Code 39, ITF (boleto), ITF-14, DataMatrix e QR, em SVG e/ou PNG. EAN/UPC sem o último dígito recebem o DV calculado.

Custo: 1 crédito(s)

Parâmetro	Onde	Descrição
`Idempotency-Key`	cabeçalho	Chave única da operação (ex.: um UUID). Repetir o mesmo pedido com a mesma chave em até 24 h devolve a resposta original, sem novo débito (cabeçalho Idempotent-Replayed: true). Mesma chave com outro pedido: 409 idempotency_key_reused.

Corpo (JSON)

Campo	Tipo	Descrição
`type` obrigatório	string code128, ean13, ean8, upca, code39, itf, itf14, datamatrix, qr	Tipo.
`value` obrigatório	string	Conteúdo.
`format`	string svg, png, both	svg (padrão), png ou both.
`module_size`	number	Largura do módulo em px.
`height`	number	Altura das barras em px (10–600).
`show_text`	boolean	Texto legível embaixo.

Resposta 200: Image

Campo	Tipo	Descrição
`width`	number	Largura (px).
`height`	number	Altura (px).
`svg`	string	SVG (format svg ou both).
`png_base64`	string	PNG em base64 (format png ou both).

Erros: 400 · 401 · 402 · 409 · 429 — veja a tabela de códigos.

Testar agora

Corpo (JSON) Enviar Idempotency-Key aleatória

Códigos de erro

Formato: {"error":{"code","message","request_id"}}. Trate pelo code (estável); a message é para pessoas e pode mudar.

HTTP	code	Quando	Tentar de novo?
400	`invalid_request`	Parâmetros ausentes ou inválidos.	não: corrija o pedido
400	`invalid_json`	O corpo não é um JSON válido.	não: corrija o pedido
400	`invalid_option`	Opção desconhecida ou com valor inválido para a ferramenta.	não: corrija o pedido
400	`missing_option`	Falta uma opção obrigatória.	não: corrija o pedido
400	`missing_files`	Nenhum arquivo enviado.	não: corrija o pedido
400	`too_few_files / too_many_files`	Quantidade de arquivos fora do permitido pela ferramenta ou pelo plano.	não: corrija o pedido
400	`unexpected_file`	Campo de arquivo desconhecido (na Expedição, use labels e xmls).	não: corrija o pedido
400	`missing_file`	Falta o arquivo extra (papel timbrado, logo).	não: corrija o pedido
400	`invalid_webhook_url`	webhook_url não é HTTPS ou aponta para rede interna.	não: corrija o pedido
400	`invalid_cnpj / invalid_cep`	Documento com formato ou dígito verificador inválido.	não: corrija o pedido
400	`declaration_required`	Desbloquear PDF exige authorized: true.	não: corrija o pedido
400	`invalid_idempotency_key`	Idempotency-Key vazia, com espaços ou com mais de 255 caracteres.	não: corrija o pedido
401	`missing_api_key`	Chave não enviada.	não: corrija o pedido
401	`invalid_api_key`	Chave inexistente.	não: corrija o pedido
401	`revoked_api_key`	Chave revogada.	não: corrija o pedido
402	`insufficient_credits`	Créditos insuficientes para a chamada.	não: corrija o pedido
402	`esign_quota`	Cota mensal de documentos para assinatura do plano esgotada (Grátis 3, Pro 30, Empresas 200).	não: corrija o pedido
403	`account_not_eligible`	A conta ainda não confirmou a maioridade.	não: corrija o pedido
404	`not_found / tool_not_found / job_not_found / file_not_found`	Recurso inexistente, expirado ou de outra conta.	não: corrija o pedido
404	`envelope_not_found`	Envelope inexistente, excluído ou de outra conta.	não: corrija o pedido
404	`lote_not_found`	Lote da Central de Expedição inexistente, expirado (30 dias) ou de outra conta.	não: corrija o pedido
409	`job_not_ready`	A tarefa ainda não terminou.	não: corrija o pedido
409	`lote_not_ready`	O lote ainda não terminou, falhou ou os arquivos expiraram (7 dias).	não: corrija o pedido
409	`job_running`	DELETE de uma tarefa em andamento (tarefas não podem ser canceladas no meio; apague depois).	não: corrija o pedido
409	`idempotency_key_reused`	A mesma Idempotency-Key foi usada nas últimas 24 h em outro pedido (outro caminho ou outro conteúdo).	não: corrija o pedido
409	`idempotency_in_progress`	Um pedido com a mesma Idempotency-Key ainda está em andamento (Retry-After).	sim, depois de `Retry-After`
409	`invalid_state`	Ação incompatível com a situação do envelope (ex.: enviar de novo, cancelar um assinado).	não: corrija o pedido
409	`envelope_not_completed`	Os PDFs final e de relatório só existem depois que todos assinam.	não: corrija o pedido
410	`envelope_gone`	O arquivo do rascunho não está mais disponível.	não: corrija o pedido
413	`file_too_large / payload_too_large`	Arquivo acima do limite do plano ou corpo JSON grande demais.	não: corrija o pedido
415	`unsupported_file_type / unsupported_media_type`	Extensão não aceita pela ferramenta, ou corpo que não é JSON.	não: corrija o pedido
422	`invalid_boleto`	Dígito verificador do boleto não confere.	não: corrija o pedido
422	`invalid_value`	Valor impossível de codificar no tipo de código de barras.	não: corrija o pedido
422	`invalid_pdf`	Arquivo que não é PDF, corrompido, protegido por senha ou com mais de 100 páginas.	não: corrija o pedido
422	`forbidden_url`	URL de arquivo aponta para rede interna/privada (bloqueado).	não: corrija o pedido
429	`rate_limited`	Limite de requisições por minuto do plano.	sim, depois de `Retry-After`
429	`concurrency_limit`	Tarefas pesadas simultâneas acima do limite do plano.	sim, depois de `Retry-After`
429	`reminder_too_soon`	Lembrete repetido em menos de 30 minutos.	sim, depois de `Retry-After`
429	`test_limit`	Chave de teste passou de 20 chamadas no dia.	sim, depois de `Retry-After`
500	`internal_error`	Erro inesperado (tente de novo).	sim, com espera e a mesma `Idempotency-Key`
502	`upstream_unavailable`	A fonte pública (Receita/CEP) não respondeu; nada é cobrado.	sim, com espera e a mesma `Idempotency-Key`

Referência da API

Conta

GET /v1/me #

GET /v1/usage #

Ferramentas de arquivo

GET /v1/tools #

GET /v1/tools/{toolId} #

POST /v1/tools/{toolId} #

Tarefas

GET /v1/jobs #

GET /v1/jobs/{id} #

POST /v1/jobs/{id}/delete #

GET /v1/jobs/{id}/files/{index} #

GET /v1/jobs/{id}/download #

Webhooks

POST /v1/webhooks/test #

Assinatura eletrônica

POST /v1/esign/envelopes #

GET /v1/esign/envelopes #

GET /v1/esign/envelopes/{id} #

POST /v1/esign/envelopes/{id}/send #

POST /v1/esign/envelopes/{id}/remind #

POST /v1/esign/envelopes/{id}/cancel #

POST /v1/esign/envelopes/{id}/delete #

GET /v1/esign/envelopes/{id}/files/final #

GET /v1/esign/envelopes/{id}/files/audit #

Central de Expedição

POST /v1/expedicao/lotes #

GET /v1/expedicao/lotes/{id} #

GET /v1/expedicao/lotes/{id}/files/{name} #

GET /v1/expedicao/lotes/{id}/download #

Dados

GET /v1/cnpj/{cnpj} #

GET /v1/cep/{cep} #

POST /v1/validate #

POST /v1/boleto/parse #

POST /v1/pix/brcode #

POST /v1/qrcode #

POST /v1/barcode #

Códigos de erro

GET `/v1/me` #

GET `/v1/usage` #

GET `/v1/tools` #

GET `/v1/tools/{toolId}` #

POST `/v1/tools/{toolId}` #

GET `/v1/jobs` #

GET `/v1/jobs/{id}` #

POST `/v1/jobs/{id}/delete` #

GET `/v1/jobs/{id}/files/{index}` #

GET `/v1/jobs/{id}/download` #

POST `/v1/webhooks/test` #

POST `/v1/esign/envelopes` #

GET `/v1/esign/envelopes` #

GET `/v1/esign/envelopes/{id}` #

POST `/v1/esign/envelopes/{id}/send` #

POST `/v1/esign/envelopes/{id}/remind` #

POST `/v1/esign/envelopes/{id}/cancel` #

POST `/v1/esign/envelopes/{id}/delete` #

GET `/v1/esign/envelopes/{id}/files/final` #

GET `/v1/esign/envelopes/{id}/files/audit` #

POST `/v1/expedicao/lotes` #

GET `/v1/expedicao/lotes/{id}` #

GET `/v1/expedicao/lotes/{id}/files/{name}` #

GET `/v1/expedicao/lotes/{id}/download` #

GET `/v1/cnpj/{cnpj}` #

GET `/v1/cep/{cep}` #

POST `/v1/validate` #

POST `/v1/boleto/parse` #

POST `/v1/pix/brcode` #

POST `/v1/qrcode` #

POST `/v1/barcode` #