Guia de Utilização da Invoice API

Versão da API: v1.0
Microserviço: XDPeople.Soba.Invoice.WebAPI

---

Visão Geral

A Invoice API é um microserviço do XDPeople.Soba responsável pela gestão completa do ciclo de vida de documentos de venda, incluindo:

• 📝 Orçamentos (Quotes)
• 📦 Encomendas (Orders)
• 📄 Faturas Proforma (Proforma Invoices)
• 🧾 Faturas (Sales Invoices)
• 💰 Recibos (Receipts)
• ↩️ Notas de Crédito (Credit Notes)

Características Principais

• ✅ Criação, atualização e consulta de documentos
• ✅ Filtros avançados (status, datas, cliente, tipo de documento)
• ✅ Paginação de resultados
• ✅ Autenticação JWT
• ✅ Multi-tenancy (suporte para múltiplos tenants)
• ✅ Arquitetura Clean Architecture com padrão CQRS
• ✅ Documentação Swagger/OpenAPI

---

Informações Técnicas

URL Base

Ambiente	URL Base	Documentação
Produção	https://api.xdsoba.com/invoice/api/v1	Swagger UI

Nota

Para ambientes de desenvolvimento local, consulte a documentação interna de configuração.

Tecnologias Utilizadas

• .NET 8.0 - Framework principal
• MediatR - Implementação do padrão CQRS
• Entity Framework Core - ORM para acesso a dados
• MySQL - Base de dados principal
• FluentValidation - Validação de comandos
• JWT Bearer Authentication - Autenticação
• Swagger/OpenAPI - Documentação da API

Health Checks

GET /health

Verifica o estado da API (memória, conectividade, etc.)

---

Autenticação

A Invoice API utiliza JWT (JSON Web Token) para autenticação.

Obter Token JWT

Para obter um token JWT, utilize o endpoint de autenticação do Gateway:

POST https://api.xdsoba.com/gateway/auth/combined-login
Content-Type: application/json

{
  "tenantKey": "XDPT.30010",
  "tenantPassword": "your-tenant-password",
  "userKey": "user@example.com",
  "userPassword": "your-user-password"
}

Utilizar o Token

Adicione o token no header Authorization de todas as requisições:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Autenticação no Swagger UI

1. Aceda ao Swagger UI
2. Clique no botão "Authorize" (🔒)
3. Insira: Bearer <seu-token-jwt>
4. Clique em "Authorize"
5. Feche o modal

---

Endpoints Disponíveis

1. Criar Documento

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}

Descrição: Cria um novo documento de venda (invoice, quote, order, etc.)

Códigos de Resposta:

• 201 Created - Documento criado com sucesso
• 400 Bad Request - Dados inválidos
• 401 Unauthorized - Não autenticado
• 500 Internal Server Error - Erro interno

2. Atualizar Documento

PUT /api/v1/invoices/{id}
Content-Type: application/json
Authorization: Bearer {token}

Descrição: Atualiza um documento existente

Códigos de Resposta:

• 200 OK - Documento atualizado com sucesso
• 400 Bad Request - Dados inválidos ou ID mismatch
• 404 Not Found - Documento não encontrado
• 409 Conflict - Conflito de concorrência
• 500 Internal Server Error - Erro interno

3. Obter Documento por ID

GET /api/v1/invoices/{id}
Authorization: Bearer {token}

Descrição: Obtém os detalhes completos de um documento pelo seu ID

Códigos de Resposta:

• 200 OK - Documento encontrado
• 404 Not Found - Documento não encontrado

4. Obter Documento por Número

GET /api/v1/invoices/{documentTypeId}/{serieId}/{number}
Authorization: Bearer {token}

Descrição: Obtém um documento pelo seu tipo, série e número

Parâmetros:

• documentTypeId (int) - ID do tipo de documento
• serieId (int) - ID da série
• number (int) - Número do documento

Códigos de Resposta:

• 200 OK - Documento encontrado
• 400 Bad Request - Parâmetros inválidos
• 404 Not Found - Documento não encontrado

5. Listar Documentos

GET /api/v1/invoices?pageNumber=1&pageSize=10&status=Open&fromDate=2025-01-01&toDate=2025-12-31
Authorization: Bearer {token}

Descrição: Lista documentos com filtros opcionais e paginação

Parâmetros de Query:

• pageNumber (int, default: 1) - Número da página
• pageSize (int, default: 10) - Tamanho da página
• status (string, opcional) - Filtrar por status (Open/Closed)
• fromDate (DateTime, opcional) - Data de criação inicial (formato: YYYY-MM-DD)
• toDate (DateTime, opcional) - Data de criação final (formato: YYYY-MM-DD)
• entityKeyId (string, opcional) - Filtrar por cliente/fornecedor
• documentTypeId (int, opcional) - Filtrar por tipo de documento
• sortBy (string, opcional) - Ordenar por campo (date/number/entity/total)
• sortDescending (bool, default: false) - Ordenação descendente

Códigos de Resposta:

• 200 OK - Lista de documentos retornada com sucesso

---

Funcionalidades Principais

1. Gestão de Documentos de Venda

A Invoice API suporta todos os tipos de documentos de venda:

Tipo de Documento	Descrição	Uso Típico	Guia Dedicado
Quote	Orçamento	Propostas comerciais	📝 Guia Orçamentos
Order	Encomenda	Pedidos de clientes	📦 Guia Encomendas
Proforma Invoice	Fatura Proforma	Faturação antecipada	⚠️ Em desenvolvimento
Sales Invoice	Fatura de Venda	Faturação definitiva	🧾 Guia Faturas
Receipt	Recibo	Comprovativo de pagamento	💰 Guia Recibos
Credit Note	Nota de Crédito	Devoluções/correções	↩️ Guia Notas Crédito

2. Cabeçalho e Linhas de Documento

Cada documento é composto por:

• Cabeçalho (Header): Informações gerais (cliente, data, totais, etc.)
• Linhas (Bodies): Itens do documento (produtos, quantidades, preços, impostos)

3. Informações de Cliente/Entidade

Os documentos podem armazenar informações completas da entidade:

• Nome/Descrição
• NIF/VAT
• Morada, Código Postal, Cidade, Estado, País
• E-mail, Telefone

4. Informações Fiscais

Suporte completo para:

• Impostos (IVA/VAT) por linha
• Segunda taxa de imposto
• Isenção de impostos
• Região fiscal

5. Informações Comerciais

• Modo de pagamento
• Data de vencimento
• Descontos (linha e cabeçalho)
• Comissões
• Referências de documentos

6. Informações Logísticas

Para documentos de transporte:

• Local de carga/descarga
• Datas de carga/descarga
• Transportador
• Armazéns (origem/destino)

7. Estado do Documento

• Open (Aberto): Documento em edição
• Closed (Fechado): Documento finalizado

8. Controlo de Inventário

• Fluxo de stock (entrada/saída)
• Comportamento de stock
• Armazéns de origem e destino

---

Modelos de Dados

CreateDocumentHeaderCommand

Campos Obrigatórios:

{
  "serieId": 1,                    // ID da série
  "documentTypeId": 5,              // ID do tipo de documento
  "entityKeyId": "CLI001",          // ID do cliente/fornecedor
  "documentBodies": [               // Linhas do documento
    {
      "itemKeyId": "PROD001",       // ID do produto/item
      "quantity": 2.0,              // Quantidade
      "retailPrice": 50.00,         // Preço unitário
      "taxId": 1,                   // ID do imposto
      "paymentType": 1,             // Tipo de pagamento
      "stockFlow": 1,               // Fluxo de stock (1=saída, -1=entrada)
      "stockBehavior": 1,           // Comportamento de stock
      "secondTaxId": 0              // Segunda taxa de imposto
    }
  ]
}

Campos Opcionais:

{
  "entityDescription": "Cliente Exemplo, Lda",
  "entityVat": "PT123456789",
  "entityAddress": "Rua Exemplo, 123",
  "entityPostalCode": "1000-000",
  "entityCity": "Lisboa",
  "entityState": "Lisboa",
  "entityCountry": "Portugal",
  "entityEmail": "cliente@exemplo.pt",
  "entityPhone": "210000000",
  "obs": "Observações do documento",
  "docReference": "PO-2025-001",
  "extraDocReference": "REF-EXTRA",
  "dueDate": "2025-12-31",
  "paymentModeId": 1,
  "paymentTypeId": 1,
  "exemptionCode": "M01",
  "exemptionReason": "Isento ao abrigo do artigo X",
  "loadPlaceDescription": "Armazém Central",
  "unloadPlaceDescription": "Loja Cliente",
  "loadPlaceDate": "2025-11-28T10:00:00",
  "unloadPlaceDate": "2025-11-28T15:00:00",
  "carrierDescription": "Transportadora XYZ",
  "taxRegionId": 1,
  "saleZoneAreaObjectId": 1,
  "guid": "550e8400-e29b-41d4-a716-446655440000"
}

UpdateDocumentCommand

{
  "id": 123,                        // Obrigatório: ID do documento
  "entityDescription": "Novo Nome", // Opcional
  "obs": "Nova observação",         // Opcional
  "docReference": "NEW-REF",        // Opcional
  "extraDocReference": "EXTRA",     // Opcional
  "dueDate": "2025-12-31",          // Opcional
  "paymentModeId": 2,               // Opcional
  "close": true,                    // Opcional: Fechar documento
  "documentBodies": [...]           // Opcional: Novas linhas
}

---

Exemplos de Utilização

Exemplo 1: Criar uma Fatura Simples

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "entityDescription": "Cliente Exemplo, Lda",
  "entityVat": "PT123456789",
  "obs": "Fatura referente ao pedido PO-2025-001",
  "docReference": "PO-2025-001",
  "dueDate": "2025-12-31",
  "paymentModeId": 1,
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Produto 1",
      "quantity": 2.0,
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 1,
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

Resposta (201 Created):

{
  "id": 123,
  "documentNumber": "FT A/001",
  "entityKeyId": "CLI001",
  "entityDescription": "Cliente Exemplo, Lda",
  "total": 190.00,
  "totalTaxes": 43.70,
  "status": "Open",
  "creationDate": "2025-11-28T10:30:00",
  "documentBodies": [...]
}

Exemplo 2: Fechar um Documento

PUT /api/v1/invoices/123
Content-Type: application/json
Authorization: Bearer {token}

{
  "id": 123,
  "close": true
}

Exemplo 3: Listar Documentos Abertos

GET /api/v1/invoices?status=Open&pageNumber=1&pageSize=20
Authorization: Bearer {token}

---

Gestão de Erros

A Invoice API utiliza códigos de status HTTP padrão e retorna respostas estruturadas para erros.

Códigos de Status

Código	Descrição	Quando Ocorre
200 OK	Sucesso	Operação bem-sucedida
201 Created	Criado	Recurso criado com sucesso
400 Bad Request	Pedido inválido	Validação falhou, dados inválidos
401 Unauthorized	Não autorizado	Token inválido ou ausente
404 Not Found	Não encontrado	Recurso não existe
409 Conflict	Conflito	Conflito de concorrência
500 Internal Server Error	Erro interno	Erro não esperado

Estrutura de Erro

{
  "message": "Descrição do erro",
  "errors": [
    "Detalhe do erro 1",
    "Detalhe do erro 2"
  ]
}

---

Boas Práticas

1. Autenticação

• ✅ Sempre incluir o token JWT no header Authorization
• ✅ Renovar o token antes de expirar
• ✅ Armazenar o token de forma segura
• ❌ Não partilhar tokens entre utilizadores

2. Criação de Documentos

• ✅ Validar todos os dados antes de enviar
• ✅ Fornecer descrições claras para itens e entidades
• ✅ Incluir referências de documentos (PO, ordem de compra, etc.)
• ✅ Definir corretamente os impostos por linha
• ✅ Verificar fluxo de stock (entrada/saída)
• ❌ Não criar documentos duplicados

3. Atualização de Documentos

• ✅ Obter sempre a versão mais recente antes de atualizar
• ✅ Atualizar apenas os campos necessários
• ✅ Fechar documentos apenas quando finalizados
• ❌ Não atualizar documentos fechados (criar nota de crédito)

4. Consulta de Documentos

• ✅ Usar paginação para listas grandes
• ✅ Aplicar filtros para reduzir volume de dados
• ✅ Usar cache quando apropriado
• ❌ Não carregar todos os documentos sem filtros

---

Próximos Passos

• 📝 Guia de Orçamentos - Criar e gerir orçamentos
• 📦 Guia de Encomendas - Processar encomendas de clientes
• 🧾 Guia de Faturas - Emitir faturas de venda
• 💰 Guia de Recibos - Registar pagamentos
• ↩️ Guia de Notas de Crédito - Processar devoluções

---

Última Atualização: 28 de Novembro de 2025
Versão do Documento: 1.0