Consultar uma solicitação fiscal
curl --request GET \
--url https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}import requests
url = "https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"fiscalRequestId": "9afef543-56ce-4911-a92e-5908366fa980",
"orderCode": "EC-K004-42-1786579046934",
"reused": false,
"countryCode": "EC",
"requestStatus": "GENERATED",
"documentStatus": "AUTHORIZED",
"retryable": false,
"environment": "PRODUCTION",
"document": {
"documentType": "SALE_INVOICE",
"documentLabel": "FACTURA",
"documentNumber": "005-004-000000045",
"authorizationMode": "ONLINE",
"authorizationLabel": "EMISION NORMAL",
"issuedAt": "2026-08-13T13:33:41.438Z",
"compensates": null
},
"printing": { "printable": true, "mode": "FISCAL_DOCUMENT", "reason": null },
"graphic": { "qr": "1208202601000000000000110050040000000451234567817" },
"failure": null,
"countryData": {
"claveAcceso": "1208202601000000000000110050040000000451234567817",
"establecimiento": "005",
"puntoEmision": "004",
"secuencial": "000000045",
"ambiente": "PRODUCCION"
}
}
}
{
"success": true,
"data": {
"fiscalRequestId": "c1a7f0e2-9b34-4d21-8e55-3f60ab12cd90",
"orderCode": "CO-K039-1786901234",
"reused": false,
"countryCode": "CO",
"requestStatus": "GENERATED",
"documentStatus": "AUTHORIZED",
"retryable": false,
"environment": "PRODUCTION",
"document": {
"documentType": "SALE_INVOICE",
"documentLabel": "FACTURA ELECTRONICA DE VENTA",
"documentNumber": "SETP990000001",
"authorizationMode": "ONLINE",
"authorizationLabel": "VALIDACION PREVIA",
"issuedAt": "2026-08-16T14:21:03.118Z",
"compensates": null
},
"printing": { "printable": true, "mode": "FISCAL_DOCUMENT", "reason": null },
"graphic": null,
"failure": null,
"countryData": {
"numeroComprobante": "SETP990000001",
"cufe": "9c4f1e… (96 caracteres hexadecimales)",
"prefijo": "SETP",
"numeroDian": "990000001",
"qrCode": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=9c4f1e…",
"ambiente": "PRODUCCION"
}
}
}
{
"success": false,
"error": "NOT_FOUND",
"message": "FiscalRequest not found"
}
API
Consultar uma solicitação fiscal
Retorna o estado atual de uma solicitação de numeração pelo identificador — incluindo o veredito do órgão quando já chegou.
GET
/
api
/
v1
/
external
/
fiscal
/
numbering
/
{fiscalRequestId}
Consultar uma solicitação fiscal
curl --request GET \
--url https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}import requests
url = "https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/external/fiscal/numbering/{fiscalRequestId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"fiscalRequestId": "9afef543-56ce-4911-a92e-5908366fa980",
"orderCode": "EC-K004-42-1786579046934",
"reused": false,
"countryCode": "EC",
"requestStatus": "GENERATED",
"documentStatus": "AUTHORIZED",
"retryable": false,
"environment": "PRODUCTION",
"document": {
"documentType": "SALE_INVOICE",
"documentLabel": "FACTURA",
"documentNumber": "005-004-000000045",
"authorizationMode": "ONLINE",
"authorizationLabel": "EMISION NORMAL",
"issuedAt": "2026-08-13T13:33:41.438Z",
"compensates": null
},
"printing": { "printable": true, "mode": "FISCAL_DOCUMENT", "reason": null },
"graphic": { "qr": "1208202601000000000000110050040000000451234567817" },
"failure": null,
"countryData": {
"claveAcceso": "1208202601000000000000110050040000000451234567817",
"establecimiento": "005",
"puntoEmision": "004",
"secuencial": "000000045",
"ambiente": "PRODUCCION"
}
}
}
{
"success": true,
"data": {
"fiscalRequestId": "c1a7f0e2-9b34-4d21-8e55-3f60ab12cd90",
"orderCode": "CO-K039-1786901234",
"reused": false,
"countryCode": "CO",
"requestStatus": "GENERATED",
"documentStatus": "AUTHORIZED",
"retryable": false,
"environment": "PRODUCTION",
"document": {
"documentType": "SALE_INVOICE",
"documentLabel": "FACTURA ELECTRONICA DE VENTA",
"documentNumber": "SETP990000001",
"authorizationMode": "ONLINE",
"authorizationLabel": "VALIDACION PREVIA",
"issuedAt": "2026-08-16T14:21:03.118Z",
"compensates": null
},
"printing": { "printable": true, "mode": "FISCAL_DOCUMENT", "reason": null },
"graphic": null,
"failure": null,
"countryData": {
"numeroComprobante": "SETP990000001",
"cufe": "9c4f1e… (96 caracteres hexadecimales)",
"prefijo": "SETP",
"numeroDian": "990000001",
"qrCode": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=9c4f1e…",
"ambiente": "PRODUCCION"
}
}
}
{
"success": false,
"error": "NOT_FOUND",
"message": "FiscalRequest not found"
}
Retorna o mesmo contrato que
É o mesmo scope de emissão, de propósito: quem pode numerar pode consultar o
que numerou. Não há um scope somente-leitura que conceda menos.
O tenant sai da chave, nunca do request. Uma solicitação de outra conta retorna
POST /numbering,
com o estado atualizado. O que muda entre uma chamada e outra é documentStatus:
nasce em PENDING e passa a AUTHORIZED quando o órgão se pronuncia.
Na operação diária você não deveria precisar disto. Os identificadores já
chegam em
data.fiscalRepresentation nos eventos do pedido, e o veredito do
órgão em lastKnown.fiscal.status. Este endpoint existe para quando o caminho
normal não basta: você perdeu a resposta síncrona por uma queda de rede, ou quer
confirmar o estado sem esperar o evento.Autenticação
| Header | x-api-key: pk_live_… |
| Scope | fiscal:write |
404, igual a uma que não existe — as duas são indistinguíveis para não vazar
quais identificadores são reais.
Parâmetros de rota
string
obrigatório
O
fiscalRequestId devolvido pela numeração. É um UUID.Resposta
Idêntica à dePOST /numbering — veja
a referência completa do contrato.
{
"success": true,
"data": {
"fiscalRequestId": "9afef543-56ce-4911-a92e-5908366fa980",
"orderCode": "EC-K004-42-1786579046934",
"reused": false,
"countryCode": "EC",
"requestStatus": "GENERATED",
"documentStatus": "AUTHORIZED",
"retryable": false,
"environment": "PRODUCTION",
"document": {
"documentType": "SALE_INVOICE",
"documentLabel": "FACTURA",
"documentNumber": "005-004-000000045",
"authorizationMode": "ONLINE",
"authorizationLabel": "EMISION NORMAL",
"issuedAt": "2026-08-13T13:33:41.438Z",
"compensates": null
},
"printing": { "printable": true, "mode": "FISCAL_DOCUMENT", "reason": null },
"graphic": { "qr": "1208202601000000000000110050040000000451234567817" },
"failure": null,
"countryData": {
"claveAcceso": "1208202601000000000000110050040000000451234567817",
"establecimiento": "005",
"puntoEmision": "004",
"secuencial": "000000045",
"ambiente": "PRODUCCION"
}
}
}
{
"success": true,
"data": {
"fiscalRequestId": "c1a7f0e2-9b34-4d21-8e55-3f60ab12cd90",
"orderCode": "CO-K039-1786901234",
"reused": false,
"countryCode": "CO",
"requestStatus": "GENERATED",
"documentStatus": "AUTHORIZED",
"retryable": false,
"environment": "PRODUCTION",
"document": {
"documentType": "SALE_INVOICE",
"documentLabel": "FACTURA ELECTRONICA DE VENTA",
"documentNumber": "SETP990000001",
"authorizationMode": "ONLINE",
"authorizationLabel": "VALIDACION PREVIA",
"issuedAt": "2026-08-16T14:21:03.118Z",
"compensates": null
},
"printing": { "printable": true, "mode": "FISCAL_DOCUMENT", "reason": null },
"graphic": null,
"failure": null,
"countryData": {
"numeroComprobante": "SETP990000001",
"cufe": "9c4f1e… (96 caracteres hexadecimales)",
"prefijo": "SETP",
"numeroDian": "990000001",
"qrCode": "https://catalogo-vpfe.dian.gov.co/document/searchqr?documentkey=9c4f1e…",
"ambiente": "PRODUCCION"
}
}
}
{
"success": false,
"error": "NOT_FOUND",
"message": "FiscalRequest not found"
}
Erros
| Código | Quando |
|---|---|
401 | A API key falta, não existe ou está revogada |
403 | A key não tem o scope fiscal:write |
404 | O fiscalRequestId não existe ou pertence a outra conta |
Relacionado
- Solicitar numeração fiscal — o
POSTque a cria - Listar solicitações de um pedido — quando você só tem o
orderCode - Dados de impressão fiscal — o que o caixa lê para reimprimir
⌘I