Fiscal Notes — Onboarding

Integration guide for the Fiscal Notes module. Before starting, complete the Connector registration and review the Authentication flow.

Flow overview

Phase 1: Activation & Binding

When a company activates the fiscal notes addon in the OlaClick panel:

1. OlaClick creates a connection between the company and your connector with status pending.
2. OlaClick creates a webhook configuration for that company, pointing to your registered webhook URL.
3. OlaClick sends a CONNECTION_CREATED event to your webhook.

The event's data field contains merchant_id, webhook_url, and subscribed_events. Store the merchant_id — it identifies the company and you'll need it for authentication.

Event reference: CONNECTION_CREATED

Phase 2: KYC

The company sees your KYC iframe embedded in the OlaClick platform and submits their fiscal documents.

1. Implement the iframe — OlaClick embeds your URL with company_id and country as query parameters. → See KYC Iframe

2. Update the connection status — Once you validate (or reject) the documents, call the API to transition the connection. This endpoint requires a Connector Token (no company_id).

   • status: "active" → KYC approved, emission flow is enabled
   • status: "rejected" → KYC rejected, no events will be sent

   → See Update Connection Status

   API Reference: PATCH /v1/conections/:id — Required scope: conections:write

dica

You can update the connection status at any time. If you need to invalidate a previously approved KYC (expired certificates, compliance issues), call the same endpoint to transition back to rejected. While the connection is not active, OlaClick stops sending events and the connector can't generate company-scoped tokens.

Phase 3: Emission

Once the connection is active, OlaClick sends invoice requests to your webhook when orders are completed.

1. Receive the event — OlaClick delivers a FISCAL_NOTES_REQUEST event. The data field contains order_id, country_code, and electronic_invoice_id.

   → See Fiscal Note Requested

   Event reference: FISCAL_NOTES_REQUEST

2. Fetch the order — The event only contains the order_id reference. Call the API to get the full order (products, totals, payments, client info). This requires a Company Token (include company_id in the token request).

   → See Get Order

   API Reference: GET /v1/orders/:id — Required scope: orders:read

3. Confirm the result — After emitting (or failing to emit) the invoice with the fiscal authority, notify OlaClick. This requires a Company Token with fiscal-notes:write.

   Outcome	status value	Description
   Invoice emitted	COMPLETED	Include invoice_number from the fiscal authority
   Emission failed	REQUEST_ERROR	Include message with the failure reason

   → See Notify Invoice

   API Reference: PATCH /v1/fiscal-notes/confirmation — Required scope: fiscal-notes:write

Phase 4: Cancellation

When a company cancels a previously issued invoice from the OlaClick panel:

1. Receive the event — OlaClick delivers a FISCAL_NOTES_CANCELATION_REQUEST event. The payload is identical to FISCAL_NOTES_REQUEST — only the event_type differs.

   → See Receive Cancellation

   Event reference: FISCAL_NOTES_CANCELATION_REQUEST

2. Confirm the result — After cancelling (or failing to cancel) the fiscal document with the authority, notify OlaClick using the same confirmation endpoint.

   Outcome	status value	Description
   Cancellation succeeded	CANCELLED	Document cancelled with the fiscal authority
   Cancellation failed	CANCELLED_ERROR	Include message with the failure reason

   → See Confirm Cancellation

   API Reference: PATCH /v1/fiscal-notes/confirmation — Required scope: fiscal-notes:write

atenção

Always confirm after processing a webhook, whether it succeeded or failed. Without confirmation, the invoice stays in a transient state indefinitely.

Homologation

Complete the homologation process to get production access.

→ See Homologation

Required Scopes

Scope	Level	Token type	Used for
conections:write	connector	Connector Token	Update connection status (KYC)
orders:read	company	Company Token	Fetch order data by ID
fiscal-notes:write	company	Company Token	Confirm invoice emission/cancellation