Facturas & Faturação

Emissão de faturas comerciais profissionais com suporte completo a descontos percentuais e em numerário (gerais e por item), notas personalizadas, cálculo automático de IVA e liquidação multi-gateway.

1. Criar Rascunho de Fatura

Cria uma nova fatura no estado draft com discriminação de itens, descontos gerais e por linha, notas de observações e termos de vencimento:

POST

/v1/invoices

Cabeçalhos HTTP Obrigatórios

Header	Tipo	Descrição
X-EDPay-Public-Key	string	Chave pública da organização (pk_live_... ou pk_test_...).
X-EDPay-Private-Key	string	Chave privada de backend (sk_live_... ou sk_test_...).
Idempotency-Key	string	Chave única de idempotência para prevenir faturas duplicadas.
Content-Type	string	`application/json`

POST /v1/invoices

cURL

curl -X  POST "https://api-pay.edutecka.com/v1/invoices" \
  -H "X-EDPay-Public-Key: <PUBLIC_KEY>" \
  -H "X-EDPay-Private-Key: <PRIVATE_KEY>" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: req_inv_9823412" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_3f8a1b2c4d5e",
  "due_date": "2026-11-20",
  "currency": "MZN",
  "notes": "Agradecemos a sua preferência. Pagamento no prazo de 15 dias úteis.",
  "terms": "Sujeito a juros de mora de 1% ao mês após a data de vencimento. Liquidação bancária em 2 a 7 dias úteis.",
  "customer_notes": "Entregar fatura e guias assinadas na recepção da sede em Maputo.",
  "discount": {
    "type": "percentage",
    "value": 5
  },
  "items": [
    {
      "description": "Consultoria em Arquitetura Cloud & DevOps",
      "quantity": 10,
      "unit_price": 2500,
      "discount": {
        "type": "percentage",
        "value": 10
      }
    },
    {
      "description": "Auditoria de Segurança & Certificação PCI",
      "quantity": 1,
      "unit_price": 5000,
      "discount": {
        "type": "fixed",
        "value": 500
      }
    }
  ],
  "tax": {
    "rate": 16
  }
}'

2. Listar Faturas

Recupere as faturas emitidas com filtros por cliente (customer_id), estado (status) e paginação:

GET

/v1/invoices

Listar Faturas

cURL

curl -X  GET "https://api-pay.edutecka.com/v1/invoices?limit=10&status=open" \
  -H "X-EDPay-Public-Key: <PUBLIC_KEY>" \
  -H "X-EDPay-Private-Key: <PRIVATE_KEY>" \
  -H "Accept: application/json"

Resposta (200 OK)

Resposta: 200 OK

{
  "data": [
    {
      "id": "inv_1029384756",
      "number": "FT 2026/0491",
      "customer_id": "cus_3f8a1b2c4d5e",
      "status": "open",
      "total_amount": 29754,
      "currency": "MZN",
      "due_date": "2026-11-20",
      "created_at": "2026-11-08T10:00:00Z"
    }
  ],
  "meta": {
    "has_more": false,
    "total_count": 1
  }
}

3. Obter Detalhes da Fatura

Consulta os dados completos da fatura, itens descritivos, notas, descontos aplicados e URL de liquidação direta:

GET

/v1/invoices/{id}

Obter Fatura

cURL

curl -X  GET "https://api-pay.edutecka.com/v1/invoices/inv_1029384756" \
  -H "X-EDPay-Public-Key: <PUBLIC_KEY>" \
  -H "X-EDPay-Private-Key: <PRIVATE_KEY>" \
  -H "Accept: application/json"

4. Finalizar Fatura (Emitir e Gerar PDF)

Transita a fatura do estado draft para open, atribuindo a numeração fiscal definitiva (ex.: FT 2026/0491) e gerando o PDF assinado digitalmente:

POST

/v1/invoices/{id}/finalize

Finalizar Fatura

cURL

curl -X  POST "https://api-pay.edutecka.com/v1/invoices/inv_1029384756/finalize" \
  -H "X-EDPay-Public-Key: <PUBLIC_KEY>" \
  -H "X-EDPay-Private-Key: <PRIVATE_KEY>" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: req_inv_finalize_9823" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta (200 OK)

Resposta: 200 OK

{
  "data": {
    "id": "inv_1029384756",
    "number": "FT 2026/0491",
    "status": "open",
    "pdf_url": "https://api-pay.edutecka.com/v1/invoices/inv_1029384756/pdf",
    "payment_url": "https://pay.edutecka.com/pay/inv_1029384756",
    "finalized_at": "2026-11-08T10:05:00Z"
  }
}

5. Anular Fatura (Void)

Marca uma fatura aberta como anulada (void), cancelando qualquer obrigação de pagamento pendente:

POST

/v1/invoices/{id}/void

Schema JSON do Pedido (JSON Schema Draft-07)

JSON Schema — VoidInvoiceRequest

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "VoidInvoiceRequest",
  "type": "object",
  "required": [
    "reason"
  ],
  "properties": {
    "reason": {
      "type": "string",
      "minLength": 5,
      "maxLength": 500
    }
  },
  "additionalProperties": false
}

Anular Fatura

cURL

curl -X  POST "https://api-pay.edutecka.com/v1/invoices/inv_1029384756/void" \
  -H "X-EDPay-Public-Key: <PUBLIC_KEY>" \
  -H "X-EDPay-Private-Key: <PRIVATE_KEY>" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: req_inv_void_9823" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Cancelamento solicitado pelo cliente antes da prestação de serviços."
}'

Resposta (200 OK)

Resposta: 200 OK

{
  "data": {
    "id": "inv_1029384756",
    "status": "void",
    "void_reason": "Cancelamento solicitado pelo cliente antes da prestação de serviços.",
    "voided_at": "2026-11-08T10:10:00Z"
  }
}