Notas fiscais
Notas fiscais de serviço registradas no Pedagogo. As notas entram por importação de arquivo XML, já emitido na prefeitura ou no portal da NFS-e. O Pedagogo não emite, não transmite e não cancela notas. Corresponde à tela Notas fiscais do menu Faturamento.
Cada nota pode ser vinculada ao faturamento que ela cobre. Essa vinculação é feita pelos endpoints de faturamento sugerido e de vínculo abaixo.
Os endereços a seguir são relativos a https://api.pedagogo.app. A nota é identificada pelo uuid.
Endpoints
| Método | Caminho | Descrição |
|---|---|---|
| GET | /invoicing/invoices | Lista as notas fiscais |
| GET | /invoicing/invoices/{uuid} | Consulta uma nota fiscal |
| POST | /invoicing/invoices/import-xml | Importa o XML de uma nota fiscal |
| GET | /invoicing/invoices/{uuid}/billing-sugestions | Faturamentos sugeridos para vincular à nota |
| PUT | /invoicing/invoices/{uuid}/save-billing | Vincula um faturamento à nota |
| DELETE | /invoicing/invoices/{uuid}/billing/{billing_uuid} | Desvincula o faturamento da nota |
| GET | /invoicing/invoices/{invoice_uuid}/services | Serviços da nota |
Listar
GET /invoicing/invoices
Lista as notas da empresa cliente.
Parâmetros de URL
| Parâmetro | Descrição |
|---|---|
search | Texto livre. Busca no nome da empresa emissora, no código, no uuid, na série e no valor da nota |
columnName e orderData | Ordena pela coluna informada e pelo sentido (asc ou desc) |
per_page e page | Paginação, conforme Convenções |
Resposta (200): lista de notas, com uuid, code, serie, date_issue, amount, status_id, status_name, company_id, name (nome da empresa emissora), customer_vendor_id, customer_vendor_name, customer_vendor_document, nature_operation_name, special_tax_regime_name e os nomes de quem importou e alterou a nota.
Consultar
GET /invoicing/invoices/{uuid}
Devolve a nota com os dados do cliente tomador, o faturamento vinculado (billing, ou null se não houver), os serviços (service) e a situação (status).
Importar
POST /invoicing/invoices/import-xml
Importa o arquivo XML de uma nota. O envio é feito em multipart/form-data, com o arquivo no campo file.
Corpo (multipart/form-data)
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
file | Sim | Arquivo | Arquivo XML da nota fiscal de serviço. Somente arquivos com extensão .xml |
O servidor reconhece o layout pelo conteúdo do arquivo. São aceitos:
- ABRASF 2.01 (lista de NFS-e);
- ABRASF 2.03 (NFS-e individual ou em lote);
- NFS-e Nacional.
Regras da importação
- Nota já importada: a nota é identificada pela chave. Se já existir, os dados são atualizados, e a nota não é duplicada.
- Empresa: a nota é vinculada à empresa cadastrada com o mesmo CNPJ ou CPF do prestador.
- Cliente (tomador): o tomador é localizado pelo CNPJ ou CPF. Se não existir, é criado. Se existir, o nome e o endereço são atualizados com os dados do XML.
- Serviço: o código do item da lista de serviços e o CNAE, quando informado, precisam existir no catálogo do sistema.
- Valor: a nota é gravada com o valor líquido da NFS-e.
- Situação: a nota entra como Autorizado. Quando o XML traz um bloco de cancelamento reconhecido pelo layout, a nota entra como Cancelado, e o faturamento vinculado é desvinculado.
- Lote: se o XML trouxer várias notas, todas são gravadas, e a resposta traz a primeira.
Resposta (200): a nota importada.
Erros
| Status | Quando |
|---|---|
| 400 | O XML não é reconhecido. Corpo: {"message": "Invalid XML format", "status": "error"} |
| 422 | O arquivo não tem extensão .xml, ou não foi enviado |
curl -X POST https://api.pedagogo.app/invoicing/invoices/import-xml \
-H "Accept: application/json" \
-H "Authorization: Bearer <token-de-sessao>" \
-F "[email protected]"
Vínculo com faturamento
GET /invoicing/invoices/{uuid}/billing-sugestions
Faturamentos sugeridos para a nota. São os faturamentos da mesma empresa cobrada da nota, que ainda não estão vinculados a nenhuma nota, e cujo total de alunos (total_students) é igual ao valor da nota. Resposta em lista, com os campos de Faturados.
PUT /invoicing/invoices/{uuid}/save-billing
Vincula um faturamento à nota. Ao vincular, o faturamento é marcado como concluído.
Corpo
| Campo | Obrigatório | Tipo | Descrição |
|---|---|---|---|
billing_id | Sim | Número | Faturamento (id, como retornado em billing-sugestions) |
Resposta (200): corpo null.
DELETE /invoicing/invoices/{uuid}/billing/{billing_uuid}
Desvincula o faturamento da nota. O faturamento é marcado como não concluído.
Resposta (200): corpo null.
Serviços
GET /invoicing/invoices/{invoice_uuid}/services
Lista os serviços da nota. Cada item traz os dados fiscais do serviço gravados na importação: description, classification_service_id, service_value, deduction_value, pis_value, confins_value, inss_value, irrf_value, csll_value, withheld_iss, iss_value, iss_withheld_value, calculation_base, rate, unconditional_discount, conditional_discount, cnae_code_id, municipal_tax_code, municipal_code, total_percentage_taxes e source_taxes.
Resposta (200): lista de serviços da nota.