Pleaxy

Emita pedidos de compra, aprove e pague faturas, e configure seu espaço de trabalho.

Referência da API

Notas de crédito

Notas de crédito que reduzem o que um comprador deve, e sua aplicação em faturas.

Mais sobre este recurso

Notas de crédito são documentos como as faturas: ListInvoices, GetInvoice e CreateInvoice também as atendem com documentType credit_note, e estas rotas são as ações próprias da nota de crédito. Uma nota de crédito reduz o que um comprador deve a um fornecedor, com linhas e imposto próprios. Um fornecedor emite uma contra a fatura que ela corrige ou para o comprador em geral (ou a envia por SubmitFeedInvoice); um comprador pode registrar uma que recebeu. Uma que indica uma fatura e não passa do total dela é aceita na hora; qualquer outra aguarda o comprador aceitá-la ou rejeitá-la. Aceitar um crédito returned_goods ou price_adjustment (ou other com correctsBilling) devolve o valor antes de impostos à linha do pedido da fatura corrigida; créditos de serviço e abatimentos não mexem no pedido. Quem liquida os créditos aceitos é uma configuração do comprador: a Pleaxy, onde eles são aplicados às faturas e reduzem o valor devido (uma fatura aprovada que os créditos cobrem por inteiro é marcada como paga com o método "credit"), ou o sistema contábil, onde as notas de crédito aceitas saem na próxima exportação de pagamento como linhas negativas. Rejeitar uma fatura devolve os créditos aplicados a ela às respectivas notas de crédito. O total da fatura e o imposto dela nunca mudam. Um memorando de crédito que a AWS ou a Azure emite contra uma conta que a sua conexão de nuvem sincroniza é registrado como nota de crédito desse provedor (source "cloud_sync", com cloudProvider), contra a fatura que ele indica quando essa fatura está na Pleaxy, uma vez por memorando.

Endpoints

Listar notas de crédito

Lista notas de crédito, com o saldo restante de cada uma.

GET/v1/workspaces/{regionId}/credit-notes

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

As notas de crédito que um comprador recebeu ou que um fornecedor emitiu (entre todos os seus compradores), da mais antiga para a mais recente, cada uma com remaining: o que ainda falta aplicar, nunca armazenado.

Erros

  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/credit-notes
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 200 OK
[ {
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
} ]

Obter nota de crédito

Recupera uma nota de crédito.

GET/v1/workspaces/{regionId}/credit-notes/{creditNoteId}

Parâmetros

  • creditNoteIdstringObrigatório

    A nota de crédito, por exemplo "CN-1A2B3C4D".

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Uma nota de crédito: o que ela corrige, o que a aceitação fez com o pedido (poEffect), as faturas em que foi aplicada ou a exportação que a levou, e o saldo restante.

Campos da resposta

  • remainingnumber

    amount − o que foi aplicado em faturas − o reembolsado. 0 depois de totalmente usada; uma nota de crédito exportada é liquidada pelo sistema contábil.

  • refundednumber

    O que o fornecedor diz que já foi reembolsado antes de enviar a nota de crédito (UBL PrepaidAmount, cXML DepositAmount). Nunca fica a aplicar.

  • poEffectobject

    Definido na aceitação: o saldo do pedido devolvido (kind release, antes de impostos, com a quantidade para mercadorias devolvidas), ou por que nenhum foi devolvido (not_a_correction, no_po, po_closed).

  • hasPdfboolean

    A nota de crédito tem o próprio PDF, anexado quando foi emitida, ou o documento a partir do qual foi registrada: GetCreditNotePdf o retorna.

  • source, cloudProviderstring, string

    source é "feed" para uma enviada por SubmitFeedInvoice (em submittedFormat) e "cloud_sync" para o memorando de crédito de um provedor (cloudProvider aws ou azure); ausente quando lançada na Pleaxy ou com CreateCreditNote.

Erros

  • 404 Not Found - Essa nota de crédito não existe neste espaço de trabalho ("Credit note <id> not found.").
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/credit-notes/{creditNoteId}
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 200 OK
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Obter PDF da nota de crédito

Baixa o PDF de uma nota de crédito.

GET/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/pdf

Parâmetros

  • creditNoteIdstringObrigatório

    A nota de crédito, por exemplo "CN-1A2B3C4D".

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

O PDF próprio da nota de crédito: o anexado quando ela foi emitida (pdfBase64), ou o documento a partir do qual foi registrada. A Pleaxy não gera um. Envie Accept: application/pdf, ou o corpo volta codificado em base64.

Erros

  • 404 Not Found - Essa nota de crédito não existe neste espaço de trabalho, ou código CREDIT_NOTE_NO_PDF: ela não tem PDF (hasPdf é false).
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/pdf
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/pdf" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 200 OK
application/pdf

Criar nota de crédito

Emite uma nota de crédito ou registra uma recebida.

POST/v1/workspaces/{regionId}/credit-notes

Corpo

  • invoiceIdstring

    A fatura que ela corrige. Não pode ser uma rejeitada. Informe este campo ou connectionId.

  • connectionIdstring

    A contraparte, quando ela não corrige uma fatura específica.

  • externalCreditNoteNumberstringObrigatório

    O seu número para ela, de 1 a 64 caracteres: letras, dígitos, '.', '_', '/' e '-', começando com letra ou dígito. Único por fornecedor dentro do comprador, sem diferenciar maiúsculas e minúsculas.

  • issueDatestringObrigatório

    YYYY-MM-DD, não pode estar no futuro nem mais de 365 dias no passado.

  • reasonstringObrigatório

    returned_goods, price_adjustment, service_credit, rebate ou other. Os dois primeiros devolvem saldo ao pedido depois de aceitos.

  • correctsBillingboolean

    Só com o motivo other: ela corrige o que foi cobrado, então também devolve saldo ao pedido.

  • notestring

    De 1 a 1000 caracteres, por exemplo o número de RMA da devolução.

  • currencystring

    ISO 4217. Obrigatório com connectionId; com invoiceId, precisa ser a moeda da fatura.

  • lineItemsArray<{ description, qty, unitPrice }>Obrigatório

    O que é creditado, antes de impostos. De 1 a 200 linhas.

  • taxAmountnumber

    O imposto creditado, incluído no total.

  • taxBreakdownArray<{ description, amount, rate? }>

    Impostos por tipo, somando taxAmount. No máximo 20.

  • pdfBase64string

    PDF da nota de crédito como emitida, codificado em base64, até 8MB. Guardado com ela (veja GetCreditNotePdf).

  • sourceImportIdstring

    Só para o comprador: a importação de fatura (ID-…) de onde a nota de crédito foi lida - o documento de nota de crédito do fornecedor, enviado e lido pela Pleaxy. O documento é guardado com a nota de crédito quando é um PDF com menos de 8MB, e a importação registra a nota de crédito. Nunca exibido ao fornecedor.

Retorna

201 Created com o objeto mostrado na resposta.

Mais detalhes

Emite uma nota de crédito (fornecedor) ou registra uma recebida (comprador). Indique exatamente um entre invoiceId (a fatura que ela corrige, da qual assume comprador, fornecedor, moeda, pedido e linha do pedido) ou connectionId (a contraparte, com currency). O total é calculado a partir das linhas e do imposto, como em CreateInvoice. Aceita na hora quando indica uma fatura e não passa do total dela; é então aplicada a essa fatura quando os créditos do comprador são liquidados na Pleaxy e a fatura não está exportada nem paga. O comprador é notificado.

Erros

  • 400 Bad Request - CREDIT_NOTE_TARGET_REQUIRED (nenhum ou ambos entre invoiceId e connectionId), CREDIT_NOTE_INVALID (correctsBilling com outro motivo, uma fatura rejeitada, uma moeda que não é a da fatura, nenhuma moeda sem fatura), ISSUE_DATE_INVALID, um pdfBase64 que não é base64, está vazio ou passa de 8MB, ou não é um PDF ("pdfBase64 doesn't decode to a PDF document (missing %PDF- header)"), ou um corpo que não passa na validação.
  • 404 Not Found - A fatura ou a conexão não é sua.
  • 409 Conflict - CREDIT_NOTE_NUMBER_TAKEN: este número já está em uso entre você e este comprador.
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
POST /v1/workspaces/{regionId}/credit-notes
Requisição
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "invoiceId": "string",
   "connectionId": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": boolean,
   "note": "string",
   "currency": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number } ],
   "taxAmount": number,
   "pdfBase64": "string"
}
Resposta · 201 Created
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Aceitar nota de crédito

Aceita uma nota de crédito.

POST/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/accept

Parâmetros

  • creditNoteIdstringObrigatório

    A nota de crédito, por exemplo "CN-1A2B3C4D".

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Aceita uma nota de crédito que aguarda aceitação. Em uma única gravação: o status dela, o saldo do pedido que uma correção devolve (nunca mais do que a fatura corrigida consumiu da linha, menos créditos anteriores) e - quando os créditos são liquidados na Pleaxy e a fatura que ela corrige pode recebê-la - a aplicação nessa fatura. O fornecedor é notificado.

Erros

  • 400 Bad Request - CREDIT_OVER_RELEASES_PO: ela devolveria mais do que a fatura consumiu da linha do pedido.
  • 409 Conflict - CREDIT_NOTE_NOT_PENDING (já aceita, rejeitada ou anulada), ou CREDIT_NOTE_CHANGED (ela mudou enquanto era aceita; recarregue e tente de novo).
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
POST /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/accept
Requisição
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/accept" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 200 OK
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Rejeitar nota de crédito

Rejeita uma nota de crédito, com um motivo.

POST/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/reject

Parâmetros

  • creditNoteIdstringObrigatório

    A nota de crédito, por exemplo "CN-1A2B3C4D".

Corpo

  • reasonstringObrigatório

    De 1 a 1000 caracteres.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Rejeita uma nota de crédito que aguarda aceitação, com um motivo que o fornecedor lê. O fornecedor é notificado.

Erros

  • 400 Bad Request - CREDIT_NOTE_INVALID: sem motivo.
  • 409 Conflict - CREDIT_NOTE_NOT_PENDING ou CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
POST /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/reject
Requisição
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/reject" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{ "reason": "string" }
Resposta · 200 OK
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Obter liquidação de créditos

Retorna onde os créditos aceitos são liquidados.

GET/v1/workspaces/{regionId}/credit-notes/settings

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Quem liquida os créditos aceitos: pleaxy (aplicados às faturas aqui) ou accounting_system (exportados para o seu ERP). Enquanto não houver escolha (chosen: false), vale accounting_system para um espaço de trabalho que já exportou faturas para pagamento, e pleaxy caso contrário.

Erros

  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/credit-notes/settings
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/settings" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 200 OK
{
   "creditSettlement": "pleaxy" | "accounting_system",
   "chosen": boolean
}

Definir liquidação de créditos

Escolhe onde os créditos aceitos são liquidados.

PUT/v1/workspaces/{regionId}/credit-notes/settings

Corpo

  • creditSettlementstringObrigatório

    "pleaxy" ou "accounting_system".

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Escolhe quem liquida os créditos aceitos. Mudar para accounting_system é recusado enquanto houver créditos em faturas não pagas; retire-os antes.

Erros

  • 400 Bad Request - CREDIT_SETTLEMENT_INVALID.
  • 409 Conflict - CREDITS_APPLIED_TO_UNPAID: há créditos aplicados a faturas não pagas.
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
PUT /v1/workspaces/{regionId}/credit-notes/settings
Requisição
curl -X PUT "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/settings" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{ "creditSettlement": "pleaxy" | "accounting_system" }
Resposta · 200 OK
{
   "creditSettlement": "pleaxy" | "accounting_system",
   "chosen": boolean
}

Listar créditos disponíveis

Lista os créditos que podem ser aplicados a uma fatura.

GET/v1/workspaces/{regionId}/invoices/{invoiceId}/available-credits

Parâmetros

  • invoiceIdstringObrigatório

    A fatura, por exemplo "INV-1A2B3C4D".

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Os créditos aceitos do fornecedor da fatura, na moeda dela, do mais antigo para o mais recente, cada um com o saldo restante e uma sugestão (até o que a fatura deve), e as notas de crédito do fornecedor que ainda aguardam aceitação. locked diz por que a fatura não pode receber créditos agora.

Erros

  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
GET /v1/workspaces/{regionId}/invoices/{invoiceId}/available-credits
Requisição
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/available-credits" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 200 OK
{
   "creditSettlement": "pleaxy" | "accounting_system",
   "locked": "exported" | "paid" | "rejected" | "otherCurrency",
   "amountDue": number,
   "currency": "string",
   "credits": [ { "creditNoteId": "string", "externalCreditNoteNumber": "string", "reason": "string", "issueDate": "string", "amount": number, "remaining": number, "suggested": number } ],
   "pending": [ { "creditNoteId": "string", "externalCreditNoteNumber": "string", "reason": "string", "amount": number } ],
   "suggestedTotal": number
}

Aplicar créditos

Aplica créditos a uma fatura.

POST/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications

Parâmetros

  • invoiceIdstringObrigatório

    A fatura, por exemplo "INV-1A2B3C4D".

Corpo

  • applicationsArray<{ creditNoteId, amount }>Obrigatório

    De 1 a 20, cada nota de crédito uma vez, cada valor no máximo o saldo restante dela.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Aplica créditos aceitos a uma fatura que não está exportada, paga, rejeitada nem devida em outra moeda - todos ou nenhum, em uma única gravação com cada nota de crédito. O valor devido diminui; o total e o imposto dele, não. Os créditos podem cobrir no máximo o que a fatura deve; uma fatura aprovada que eles cobrem por inteiro é marcada como paga com o método "credit" (uma não aprovada, depois de aprovada). O fornecedor é notificado. Retorna a fatura.

Erros

  • 400 Bad Request - CREDIT_APPLICATIONS_REQUIRED, CREDIT_APPLICATIONS_INVALID (uma nota de crédito listada duas vezes, em outra moeda ou de outro fornecedor) ou CREDIT_OVER_APPLIED (mais do que o saldo restante de uma nota de crédito, ou mais do que a fatura deve).
  • 409 Conflict - INVOICE_LOCKED (exportada, paga, rejeitada ou devida em outra moeda), CREDIT_NOTE_NOT_ACCEPTED, CREDITS_SETTLED_IN_ACCOUNTING (o seu sistema contábil liquida os créditos) ou CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
POST /v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications
Requisição
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{ "applications": [ { "creditNoteId": "string", "amount": number } ] }
Resposta · 200 OK
{
   "documentType": "invoice" | "debit_note",
   "amendsInvoiceId": "string",
   "amendsExternalInvoiceNumber": "string",
   "debitNoteIds": [ "string" ],
   "replacesInvoiceIds": [ "string" ],
   "replacedByInvoiceIds": [ "string" ],
   "replacement": { "creditedInFull": boolean, "uncredited": number },
   "uncreditedOriginals": [ { "invoiceId": "string", "externalInvoiceNumber": "string", "uncredited": number, "currency": "string" } ],
   "id": "string",
   "po": "string",
   "poLineNo": number,
   "billsNoPoLine": true,
   "buyerOrgId": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "amount": number,
   "currency": "string",
   "usageAmount": number,
   "usageCurrency": "string",
   "tolerancePct": number,
   "matchStatus": "pending" | "matched" | "discrepancy" | "unverified",
   "unverifiedReason": "no_purchase_order" | "no_billing_connection" | "debit_note",
   "discrepancyReason": "amount" | "currency",
   "paid": boolean,
   "dueInDays": number,
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "createdAt": "string",
   "lastRemindedAt": "string",
   "rejection": { "reasonCode": "amount_incorrect" | "not_ordered_or_not_received" | "duplicate" | "missing_or_wrong_po" | "wrong_billing_entity" | "other", "reason": "string", "at": "string" },
   "replacesInvoiceId": "string",
   "source": "po-flip" | "direct" | "manual" | "feed",
   "submittedFormat": "json" | "cxml" | "ubl",
   "submittedBy": "string",
   "externalInvoiceNumber": "string",
   "lineItems": [
      { "description": "string", "qty": number, "unitPrice": number, "discount": number, "charge": number, "amount": number }
   ],
   "adjustments": [
      { "type": "discount" | "charge", "description": "string", "amount": number }
   ],
   "taxAmount": number,
   "taxBreakdown": [ { "description": "string", "rate": number, "amount": number } ],
   "paymentCurrencyAmount": { "currencyCode": "string", "totalAmount": number, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "taxCurrencyAmount": { "currencyCode": "string", "amountBreakdown": { "taxes": { "totalAmount": number } }, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "baseCurrencyAmount": { "currencyCode": "string", "totalAmount": number },
   "rateWarnings": [
      { "object": "payment" | "tax", "currency": "string", "statedRate": number, "referenceRate": number, "source": "provider" | "override", "asOf": "string", "deviationPct": number }
   ],
   "withholdings": [ { "description": "string", "rate": number, "amount": number } ],
   "deductions": [ { "kind": "prepayment" | "credit", "description": "string", "amount": number, "reference": "string", "paidOn": "string", "sourceInvoiceId": "string", "stated": true } ],
   "invoiceKind": "prepayment",
   "creditNoteIds": [ "string" ],
   "creditApplications": [ { "id": "string", "creditNoteId": "string", "externalCreditNoteNumber": "string", "amount": number, "appliedAt": "string", "appliedByName": "string", "auto": true } ],
   "payment": { "status": "recorded", "method": "ach" | "wire" | "check" | "card" | "other" | "credit", "paymentDate": "string", "reference": "string", "paidAmount": { "amount": number, "currency": "string", "rate": number, "rateDate": "string" } },
   "remittances": [ { "id": "string", "sentAt": "string", "sentByName": "string", "note": "string", "file": { "fileName": "string", "contentType": "application/pdf" | "image/png" | "image/jpeg", "sizeBytes": number } } ]
}

Remover aplicação de crédito

Remove um crédito de uma fatura.

DELETE/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications/{applicationId}

Parâmetros

  • invoiceIdstringObrigatório

    A fatura, por exemplo "INV-1A2B3C4D".

  • applicationIdstringObrigatório

    A aplicação, de creditApplications da fatura.

Retorna

200 OK com o objeto mostrado na resposta.

Mais detalhes

Retira um crédito de uma fatura que não está exportada nem paga; ele volta para a nota de crédito. Retorna a fatura.

Erros

  • 404 Not Found - A fatura não tem essa aplicação.
  • 409 Conflict - INVOICE_LOCKED (exportada ou paga) ou CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - Nenhuma credencial foi apresentada, ou o token Bearer / valor de X-Api-Key está ausente, é inválido, expirou ou foi revogado.
  • 403 Forbidden - O token Bearer ou a chave de API de quem chama não dá acesso a este espaço de trabalho (regionId), ou não tem a função exigida.
DELETE /v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications/{applicationId}
Requisição
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications/{applicationId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Resposta · 200 OK
{
   "documentType": "invoice" | "debit_note",
   "amendsInvoiceId": "string",
   "amendsExternalInvoiceNumber": "string",
   "debitNoteIds": [ "string" ],
   "replacesInvoiceIds": [ "string" ],
   "replacedByInvoiceIds": [ "string" ],
   "replacement": { "creditedInFull": boolean, "uncredited": number },
   "uncreditedOriginals": [ { "invoiceId": "string", "externalInvoiceNumber": "string", "uncredited": number, "currency": "string" } ],
   "id": "string",
   "po": "string",
   "poLineNo": number,
   "billsNoPoLine": true,
   "buyerOrgId": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "amount": number,
   "currency": "string",
   "usageAmount": number,
   "usageCurrency": "string",
   "tolerancePct": number,
   "matchStatus": "pending" | "matched" | "discrepancy" | "unverified",
   "unverifiedReason": "no_purchase_order" | "no_billing_connection" | "debit_note",
   "discrepancyReason": "amount" | "currency",
   "paid": boolean,
   "dueInDays": number,
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "createdAt": "string",
   "lastRemindedAt": "string",
   "rejection": { "reasonCode": "amount_incorrect" | "not_ordered_or_not_received" | "duplicate" | "missing_or_wrong_po" | "wrong_billing_entity" | "other", "reason": "string", "at": "string" },
   "replacesInvoiceId": "string",
   "source": "po-flip" | "direct" | "manual" | "feed",
   "submittedFormat": "json" | "cxml" | "ubl",
   "submittedBy": "string",
   "externalInvoiceNumber": "string",
   "lineItems": [
      { "description": "string", "qty": number, "unitPrice": number, "discount": number, "charge": number, "amount": number }
   ],
   "adjustments": [
      { "type": "discount" | "charge", "description": "string", "amount": number }
   ],
   "taxAmount": number,
   "taxBreakdown": [ { "description": "string", "rate": number, "amount": number } ],
   "paymentCurrencyAmount": { "currencyCode": "string", "totalAmount": number, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "taxCurrencyAmount": { "currencyCode": "string", "amountBreakdown": { "taxes": { "totalAmount": number } }, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "baseCurrencyAmount": { "currencyCode": "string", "totalAmount": number },
   "rateWarnings": [
      { "object": "payment" | "tax", "currency": "string", "statedRate": number, "referenceRate": number, "source": "provider" | "override", "asOf": "string", "deviationPct": number }
   ],
   "withholdings": [ { "description": "string", "rate": number, "amount": number } ],
   "deductions": [ { "kind": "prepayment" | "credit", "description": "string", "amount": number, "reference": "string", "paidOn": "string", "sourceInvoiceId": "string", "stated": true } ],
   "invoiceKind": "prepayment",
   "creditNoteIds": [ "string" ],
   "creditApplications": [ { "id": "string", "creditNoteId": "string", "externalCreditNoteNumber": "string", "amount": number, "appliedAt": "string", "appliedByName": "string", "auto": true } ],
   "payment": { "status": "recorded", "method": "ach" | "wire" | "check" | "card" | "other" | "credit", "paymentDate": "string", "reference": "string", "paidAmount": { "amount": number, "currency": "string", "rate": number, "rateDate": "string" } },
   "remittances": [ { "id": "string", "sentAt": "string", "sentByName": "string", "note": "string", "file": { "fileName": "string", "contentType": "application/pdf" | "image/png" | "image/jpeg", "sizeBytes": number } } ]
}
Fale conosco