{ "openapi": "3.1.0", "info": { "title": "OficialData — API de consultas", "version": "v1", "summary": "Consultas em fontes oficiais com preço conhecido antes da execução.", "description": "Cada consulta tem dois endpoints: `POST /v1/orcamento/{fonte}` diz o preço e a disponibilidade do alvo REAL sem executar e sem cobrar, e `POST /v1/consultas/{fonte}` executa e debita.\n\nO endpoint que cobra responde `202` com um protocolo — a consulta roda em fila. O resultado se busca em `GET /v1/consultas/{protocolo}`, que não cobra e não chama a origem de novo.\n\nToda resposta usa o mesmo envelope, inclusive as de erro. `header.billable` diz se aquela chamada foi faturada e `header.price` o que foi debitado — o valor debitado, não o de tabela.", "contact": { "name": "OficialData", "email": "contato@oficialdata.com.br", "url": "https://oficialdata.com.br/apis" } }, "servers": [ { "url": "https://api.oficialdata.com.br", "description": "Produção" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Token", "description": "Introspecção da própria credencial. Não cobra e não chama origem." }, { "name": "Pesquisa Prévia de Bens", "description": "Busca reversa de imóveis por CPF/CNPJ nos cartórios de registro de imóveis de um estado." }, { "name": "Visualização de Matrícula", "description": "O inteiro conteúdo de uma matrícula de imóvel, direto do registro de imóveis, em minutos." }, { "name": "Certidão de Inteiro Teor", "description": "A certidão de inteiro teor da matrícula, com fé pública e assinatura digital do cartório." } ], "paths": { "/v1/token": { "get": { "tags": [ "Token" ], "summary": "Quem sou eu, o que posso e até quando", "description": "Existe para que a primeira prova de que o token e o escopo estão certos não seja uma consulta PAGA. Não cobra e não chama origem nenhuma.", "operationId": "introspecaoToken", "responses": { "200": { "description": "Token válido. `data[0]` traz a conta, os escopos e a validade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Token ausente, malformado, revogado ou expirado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/v1/orcamento/pesquisa-previa-bens": { "post": { "tags": [ "Pesquisa Prévia de Bens" ], "summary": "Preço e disponibilidade — sem executar e sem cobrar", "description": "Obrigatório, não conveniência: o emolumento de fonte de repasse varia por UF, e sem orçar o cliente só descobriria o custo na fatura.", "operationId": "orcamento_pesquisa_previa_bens", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cpf_cnpj": { "type": "string", "description": "CPF (11 dígitos) ou CNPJ (14 dígitos) do alvo da busca. Aceita com ou sem máscara.", "examples": [ "12345678000190" ] }, "uf": { "type": "string", "description": "🔴 UMA UF por chamada — é assim que a origem funciona. Busca nacional são 26 chamadas e 26 cobranças. Ver a nota \"Uma UF por pedido\".", "examples": [ "SP" ] }, "nome": { "type": "string", "description": "Nome do alvo, quando conhecido. Ajuda a origem a desambiguar e volta na resposta como `pesquisado_nome`, para conferência.", "examples": [ "EMPRESA EXEMPLO LTDA" ] }, "finalidade": { "type": "integer", "description": "Declaração AO CARTÓRIO, não preferência técnica. `1` = avaliação de crédito · `2` = investigação jurídica sobre o imóvel e sua titularidade (padrão) · `3` = o solicitante É titular de direito real. Ver a nota \"Finalidade é declaração legal\".", "examples": [ 2 ] } }, "required": [ "cpf_cnpj", "uf" ] }, "example": { "cpf_cnpj": "12345678000190", "uf": "SP", "nome": "EMPRESA EXEMPLO LTDA", "finalidade": 2 } } } }, "responses": { "200": { "description": "Orçamento. `header.price` é 0,00 — orçar não cobra; o valor da consulta vem em `data[0]`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Token ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Token sem o escopo `consultas:pesquisa-previa-bens`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "422": { "description": "Payload inválido. `errors` lista campo a campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Limite de requisições. Respeite o `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/v1/consultas/pesquisa-previa-bens": { "post": { "tags": [ "Pesquisa Prévia de Bens" ], "summary": "Executar a consulta (cobra)", "description": "🔴 **Este endpoint COBRA.** Responde `202` com protocolo; o resultado sai em `GET /v1/consultas/{protocolo}`.\n\nLatência medida: p50 72s.", "operationId": "consultar_pesquisa_previa_bens", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "🔴 Cabeçalho HTTP, obrigatório: cada chamada protocola um ato e debita emolumento; sem esta chave um retry seu paga duas vezes. Janela de 24 h. Nunca use CPF/CNPJ como chave — documento pessoal em header fica em log de acesso. Ver a nota \"Repetir custa dinheiro de verdade\".", "schema": { "type": "string", "format": "uuid", "examples": [ "a3f1c9e2-7b40-4c11-9d8e-2f6b5a0c1d33" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cpf_cnpj": { "type": "string", "description": "CPF (11 dígitos) ou CNPJ (14 dígitos) do alvo da busca. Aceita com ou sem máscara.", "examples": [ "12345678000190" ] }, "uf": { "type": "string", "description": "🔴 UMA UF por chamada — é assim que a origem funciona. Busca nacional são 26 chamadas e 26 cobranças. Ver a nota \"Uma UF por pedido\".", "examples": [ "SP" ] }, "nome": { "type": "string", "description": "Nome do alvo, quando conhecido. Ajuda a origem a desambiguar e volta na resposta como `pesquisado_nome`, para conferência.", "examples": [ "EMPRESA EXEMPLO LTDA" ] }, "finalidade": { "type": "integer", "description": "Declaração AO CARTÓRIO, não preferência técnica. `1` = avaliação de crédito · `2` = investigação jurídica sobre o imóvel e sua titularidade (padrão) · `3` = o solicitante É titular de direito real. Ver a nota \"Finalidade é declaração legal\".", "examples": [ 2 ] } }, "required": [ "cpf_cnpj", "uf" ] }, "example": { "cpf_cnpj": "12345678000190", "uf": "SP", "nome": "EMPRESA EXEMPLO LTDA", "finalidade": 2 } } } }, "responses": { "202": { "description": "Aceita e faturada. `data[0].protocolo` é o número do acompanhamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Token ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Token sem o escopo `consultas:pesquisa-previa-bens`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "422": { "description": "Payload inválido — recusada SEM cobrar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Limite de requisições. Respeite o `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/v1/orcamento/visualizacao-matricula": { "post": { "tags": [ "Visualização de Matrícula" ], "summary": "Preço e disponibilidade — sem executar e sem cobrar", "description": "Obrigatório, não conveniência: o emolumento de fonte de repasse varia por UF, e sem orçar o cliente só descobriria o custo na fatura.", "operationId": "orcamento_visualizacao_matricula", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cpf_cnpj": { "type": "string", "description": "🔴 O CONSULENTE, não o dono do imóvel. É a quem a consulta fica associada na sua conta e no seu extrato — o documento sai do imóvel, não deste CPF/CNPJ. Aceita com ou sem máscara.", "examples": [ "12345678000190" ] }, "imovel_matricula": { "type": "string", "description": "Número da matrícula OU o CNM (Código Nacional de Matrícula). Zeros à esquerda são aceitos.", "examples": [ "21916" ] }, "imovel_cartorio": { "type": "integer", "description": "🔴 O NÚMERO do registro de imóveis, inteiro: `1` para o 1º RI. Mandar \"1º RI - Taquaritinga\" é `607` faturado pela origem.", "examples": [ 1 ] }, "imovel_municipio": { "type": "string", "description": "🔴 Município DO CARTÓRIO, não do imóvel. Medido em 2026-08-11: um imóvel de Fernando Prestes está matriculado no RI de Taquaritinga. Errar aqui não protocola nada — a cotação falha e a consulta fica indisponível sem cobrar.", "examples": [ "Taquaritinga" ] }, "imovel_uf": { "type": "string", "description": "UF do cartório.", "examples": [ "SP" ] }, "imovel_finalidade": { "type": "integer", "description": "🔴 Declaração AO CARTÓRIO, não parâmetro técnico. `1` = investigação para avaliação de crédito ou solvência · `2` = investigação jurídica sobre o imóvel e sua titularidade (padrão) · `3` = o solicitante É titular de direito real sobre o imóvel. Ver a nota \"Finalidade é declaração legal\".", "examples": [ 2 ] } }, "required": [ "cpf_cnpj", "imovel_matricula", "imovel_cartorio", "imovel_municipio", "imovel_uf" ] }, "example": { "cpf_cnpj": "12345678000190", "imovel_matricula": "21916", "imovel_cartorio": 1, "imovel_municipio": "Taquaritinga", "imovel_uf": "SP", "imovel_finalidade": 2 } } } }, "responses": { "200": { "description": "Orçamento. `header.price` é 0,00 — orçar não cobra; o valor da consulta vem em `data[0]`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Token ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Token sem o escopo `consultas:visualizacao-matricula`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "422": { "description": "Payload inválido. `errors` lista campo a campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Limite de requisições. Respeite o `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/v1/consultas/visualizacao-matricula": { "post": { "tags": [ "Visualização de Matrícula" ], "summary": "Executar a consulta (cobra)", "description": "🔴 **Este endpoint COBRA.** Responde `202` com protocolo; o resultado sai em `GET /v1/consultas/{protocolo}`.", "operationId": "consultar_visualizacao_matricula", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "🔴 Cabeçalho HTTP, obrigatório: cada chamada debita emolumento de cartório. Janela de 24 h. Nunca use CPF/CNPJ como chave — documento pessoal em header fica em log de acesso.", "schema": { "type": "string", "format": "uuid", "examples": [ "a3f1c9e2-7b40-4c11-9d8e-2f6b5a0c1d33" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cpf_cnpj": { "type": "string", "description": "🔴 O CONSULENTE, não o dono do imóvel. É a quem a consulta fica associada na sua conta e no seu extrato — o documento sai do imóvel, não deste CPF/CNPJ. Aceita com ou sem máscara.", "examples": [ "12345678000190" ] }, "imovel_matricula": { "type": "string", "description": "Número da matrícula OU o CNM (Código Nacional de Matrícula). Zeros à esquerda são aceitos.", "examples": [ "21916" ] }, "imovel_cartorio": { "type": "integer", "description": "🔴 O NÚMERO do registro de imóveis, inteiro: `1` para o 1º RI. Mandar \"1º RI - Taquaritinga\" é `607` faturado pela origem.", "examples": [ 1 ] }, "imovel_municipio": { "type": "string", "description": "🔴 Município DO CARTÓRIO, não do imóvel. Medido em 2026-08-11: um imóvel de Fernando Prestes está matriculado no RI de Taquaritinga. Errar aqui não protocola nada — a cotação falha e a consulta fica indisponível sem cobrar.", "examples": [ "Taquaritinga" ] }, "imovel_uf": { "type": "string", "description": "UF do cartório.", "examples": [ "SP" ] }, "imovel_finalidade": { "type": "integer", "description": "🔴 Declaração AO CARTÓRIO, não parâmetro técnico. `1` = investigação para avaliação de crédito ou solvência · `2` = investigação jurídica sobre o imóvel e sua titularidade (padrão) · `3` = o solicitante É titular de direito real sobre o imóvel. Ver a nota \"Finalidade é declaração legal\".", "examples": [ 2 ] } }, "required": [ "cpf_cnpj", "imovel_matricula", "imovel_cartorio", "imovel_municipio", "imovel_uf" ] }, "example": { "cpf_cnpj": "12345678000190", "imovel_matricula": "21916", "imovel_cartorio": 1, "imovel_municipio": "Taquaritinga", "imovel_uf": "SP", "imovel_finalidade": 2 } } } }, "responses": { "202": { "description": "Aceita e faturada. `data[0].protocolo` é o número do acompanhamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Token ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Token sem o escopo `consultas:visualizacao-matricula`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "422": { "description": "Payload inválido — recusada SEM cobrar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Limite de requisições. Respeite o `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/v1/orcamento/certidao-inteiro-teor": { "post": { "tags": [ "Certidão de Inteiro Teor" ], "summary": "Preço e disponibilidade — sem executar e sem cobrar", "description": "Obrigatório, não conveniência: o emolumento de fonte de repasse varia por UF, e sem orçar o cliente só descobriria o custo na fatura.", "operationId": "orcamento_certidao_inteiro_teor", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cpf_cnpj": { "type": "string", "description": "🔴 O CONSULENTE, não o dono do imóvel. É a quem a consulta fica associada na sua conta e no seu extrato — o documento sai do imóvel, não deste CPF/CNPJ. Aceita com ou sem máscara.", "examples": [ "12345678000190" ] }, "imovel_matricula": { "type": "string", "description": "Número da matrícula OU o CNM (Código Nacional de Matrícula). Zeros à esquerda são aceitos.", "examples": [ "21916" ] }, "imovel_cartorio": { "type": "integer", "description": "🔴 O NÚMERO do registro de imóveis, inteiro: `1` para o 1º RI. Mandar \"1º RI - Taquaritinga\" é `607` faturado pela origem.", "examples": [ 1 ] }, "imovel_municipio": { "type": "string", "description": "🔴 Município DO CARTÓRIO, não do imóvel. Medido em 2026-08-11: um imóvel de Fernando Prestes está matriculado no RI de Taquaritinga. Errar aqui não protocola nada — a cotação falha e a consulta fica indisponível sem cobrar.", "examples": [ "Taquaritinga" ] }, "imovel_uf": { "type": "string", "description": "UF do cartório.", "examples": [ "SP" ] } }, "required": [ "cpf_cnpj", "imovel_matricula", "imovel_cartorio", "imovel_municipio", "imovel_uf" ] }, "example": { "cpf_cnpj": "12345678000190", "imovel_matricula": "21916", "imovel_cartorio": 1, "imovel_municipio": "Taquaritinga", "imovel_uf": "SP" } } } }, "responses": { "200": { "description": "Orçamento. `header.price` é 0,00 — orçar não cobra; o valor da consulta vem em `data[0]`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Token ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Token sem o escopo `consultas:certidao-inteiro-teor`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "422": { "description": "Payload inválido. `errors` lista campo a campo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Limite de requisições. Respeite o `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/v1/consultas/certidao-inteiro-teor": { "post": { "tags": [ "Certidão de Inteiro Teor" ], "summary": "Executar a consulta (cobra)", "description": "🔴 **Este endpoint COBRA.** Responde `202` com protocolo; o resultado sai em `GET /v1/consultas/{protocolo}`.", "operationId": "consultar_certidao_inteiro_teor", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "🔴 Cabeçalho HTTP, obrigatório e mais crítico aqui do que em qualquer outra API nossa: o emolumento é o maior da plataforma e a certidão NÃO tem rota de reconciliação. Janela de 24 h.", "schema": { "type": "string", "format": "uuid", "examples": [ "a3f1c9e2-7b40-4c11-9d8e-2f6b5a0c1d33" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cpf_cnpj": { "type": "string", "description": "🔴 O CONSULENTE, não o dono do imóvel. É a quem a consulta fica associada na sua conta e no seu extrato — o documento sai do imóvel, não deste CPF/CNPJ. Aceita com ou sem máscara.", "examples": [ "12345678000190" ] }, "imovel_matricula": { "type": "string", "description": "Número da matrícula OU o CNM (Código Nacional de Matrícula). Zeros à esquerda são aceitos.", "examples": [ "21916" ] }, "imovel_cartorio": { "type": "integer", "description": "🔴 O NÚMERO do registro de imóveis, inteiro: `1` para o 1º RI. Mandar \"1º RI - Taquaritinga\" é `607` faturado pela origem.", "examples": [ 1 ] }, "imovel_municipio": { "type": "string", "description": "🔴 Município DO CARTÓRIO, não do imóvel. Medido em 2026-08-11: um imóvel de Fernando Prestes está matriculado no RI de Taquaritinga. Errar aqui não protocola nada — a cotação falha e a consulta fica indisponível sem cobrar.", "examples": [ "Taquaritinga" ] }, "imovel_uf": { "type": "string", "description": "UF do cartório.", "examples": [ "SP" ] } }, "required": [ "cpf_cnpj", "imovel_matricula", "imovel_cartorio", "imovel_municipio", "imovel_uf" ] }, "example": { "cpf_cnpj": "12345678000190", "imovel_matricula": "21916", "imovel_cartorio": 1, "imovel_municipio": "Taquaritinga", "imovel_uf": "SP" } } } }, "responses": { "202": { "description": "Aceita e faturada. `data[0].protocolo` é o número do acompanhamento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Token ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Token sem o escopo `consultas:certidao-inteiro-teor`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "422": { "description": "Payload inválido — recusada SEM cobrar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Limite de requisições. Respeite o `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/v1/consultas/{protocolo}": { "get": { "tags": [ "Token" ], "summary": "Resultado de uma consulta já pedida", "description": "Lê a linha que o motor escreveu. NÃO cobra e não fala com a origem — polling que reexecuta é polling que cobra duas vezes. Enquanto está em fila responde `202` com `consultar_daqui_s`.", "operationId": "consultarProtocolo", "parameters": [ { "name": "protocolo", "in": "path", "required": true, "description": "O `data[0].protocolo` devolvido pelo `202` da consulta.", "schema": { "type": "string", "pattern": "^[0-9]+$" } } ], "responses": { "200": { "description": "Consulta concluída. `data[0]` traz o resultado da fonte — o formato varia por fonte.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" }, "examples": { "pesquisa-previa-bens": { "summary": "Pesquisa Prévia de Bens", "value": { "code": 200, "code_message": "OK", "header": { "billable": true, "price": 1, "api_version": "v1", "request_id": "00000000-0000-0000-0000-000000000000" }, "data_count": 1, "data": [ { "code": 202, "code_message": "Consulta aceita e em execução.", "header": { "billable": true, "price": 12.19, "api_version": "v1" }, "data_count": 1, "data": [ { "protocolo": "4713", "estado": "processando", "consultar_em": "/v1/consultas/4713", "consultar_daqui_s": 72 } ], "site_receipts": [], "errors": [] } ], "site_receipts": [], "errors": [] } }, "visualizacao-matricula": { "summary": "Visualização de Matrícula", "value": { "code": 200, "code_message": "OK", "header": { "billable": true, "price": 1, "api_version": "v1", "request_id": "00000000-0000-0000-0000-000000000000" }, "data_count": 1, "data": [ { "code": 202, "code_message": "Consulta aceita.", "header": { "billable": true, "price": 28.85, "api_version": "v1" }, "data_count": 1, "data": [ { "protocolo": "4711", "estado": "processando", "consultar_em": "/v1/consultas/4711", "consultar_daqui_s": 30 } ], "site_receipts": [], "errors": [] } ], "site_receipts": [], "errors": [] } }, "certidao-inteiro-teor": { "summary": "Certidão de Inteiro Teor", "value": { "code": 200, "code_message": "OK", "header": { "billable": true, "price": 1, "api_version": "v1", "request_id": "00000000-0000-0000-0000-000000000000" }, "data_count": 1, "data": [ { "code": 202, "code_message": "Consulta aceita.", "header": { "billable": true, "price": 96.83, "api_version": "v1" }, "data_count": 1, "data": [ { "protocolo": "4712", "estado": "processando", "consultar_em": "/v1/consultas/4712", "consultar_daqui_s": 30 } ], "site_receipts": [], "errors": [] } ], "site_receipts": [], "errors": [] } } } } } }, "202": { "description": "Ainda em execução. Consulte de novo em `data[0].consultar_daqui_s` segundos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Token ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Protocolo inexistente ou de outra conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/v1/consultas/{protocolo}/documento": { "get": { "tags": [ "Token" ], "summary": "O documento que a consulta entregou", "description": "Serve o arquivo que o motor arquivou. Existe porque a URL da ORIGEM expira em ~7 dias: sem esta rota, todo documento pago viraria link morto na semana seguinte. Não cobra.", "operationId": "baixarDocumento", "parameters": [ { "name": "protocolo", "in": "path", "required": true, "description": "O `data[0].protocolo` devolvido pelo `202` da consulta.", "schema": { "type": "string", "pattern": "^[0-9]+$" } } ], "responses": { "200": { "description": "O documento.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Token ausente ou inválido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Protocolo inexistente, de outra conta, ou consulta sem documento.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Token emitido em `/app/apis/tokens`. Cada token carrega os escopos das fontes que pode chamar (`consultas:{fonte}`). Token na query string é recusado: a URL vive em log de proxy e no `Referer`." } }, "schemas": { "Envelope": { "type": "object", "description": "O envelope de TODA resposta, inclusive as de erro. Nada dentro de `data` pode reusar nome do envelope (`code`, `header`, `errors`).", "required": [ "code", "code_message", "header", "data_count", "data", "errors" ], "properties": { "code": { "type": "integer", "description": "Erro de TRANSPORTE espelha o status HTTP (401, 403, 422, 429). A faixa 6xx é reservada ao RESULTADO da consulta (\"nada consta\", \"origem fora do ar\")." }, "code_message": { "type": "string" }, "header": { "type": "object", "required": [ "billable", "price", "api_version", "request_id" ], "properties": { "billable": { "type": "boolean", "description": "Toda resposta declara se foi faturada — inclusive a que falhou." }, "price": { "type": "number", "description": "O que foi DEBITADO, não o de tabela. Sem cobrança é 0.0." }, "api_version": { "type": "string" }, "request_id": { "type": "string", "format": "uuid", "description": "É o número a citar no chamado — casa com a linha do nosso log." } } }, "data_count": { "type": "integer" }, "data": { "type": "array", "description": "SEMPRE lista, mesmo com um item só: parser de objeto quebra no dia do segundo item.", "items": { "type": "object" } }, "site_receipts": { "type": "array", "items": { "type": "string" }, "description": "Comprovantes da origem, quando ela emite." }, "errors": { "type": "array", "items": { "type": "string" } } } } } } }