openapi: 3.0.0 info: title: Fonoa Onboarding API description: > API for registering companies and individuals as transaction participants (suppliers and customers) in Fonoa's platform. Supports creating, updating, deleting, and retrieving company and individual participant profiles required for tax compliance workflows. version: 1.0.0 servers: - url: https://api-demo.fonoa.com description: Fonoa API demo environment - url: https://sandbox.fonoa.com/ description: Fonoa API sandbox environment - url: https://api.fonoa.com description: Fonoa API production (live) environment paths: /onboarding/v2/companies: post: summary: Onboard a company description: > Register a company (supplier or customer) into the Fonoa platform. Each transaction consists of at least two parties: Supplier and Customer. Use this endpoint to onboard supplier companies and B2B customer companies. For B2C individual customers, use the individual onboarding endpoint. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OnboardingCompanyRequest' responses: '202': description: Accepted - company was successfully onboarded. content: application/json: schema: $ref: '#/components/schemas/ApiResponseWrapperOnboardingAccepted' '400': description: Bad customer request - some of the provided information is incorrect or mandatory data is missing. content: application/json: schema: $ref: '#/components/schemas/ApiResponseWrapperEmpty' '401': description: Authentication failed - missing or incorrect subscription key. '409': description: Conflict - the company already exists. '429': description: Too many requests were sent for a short period of time. Try again a bit later. '5XX': description: Internal server error. Retry again later. content: application/json: schema: $ref: '#/components/schemas/ApiResponseWrapperEmpty' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Ocp-Apim-Subscription-Key schemas: ApiResponseWrapperEmpty: type: object properties: data: type: string errors: type: array description: List of errors for request. Returns null if successful. items: $ref: '#/components/schemas/ErrorResponse' message: type: string status: type: string description: The status of the request. ApiResponseWrapperOnboardingAccepted: type: object properties: data: allOf: - $ref: '#/components/schemas/OnboardingAccepted' type: object errors: type: array description: List of errors for the job. Returns null if successful. items: $ref: '#/components/schemas/ErrorResponse' message: type: string status: type: string example: success ErrorResponse: type: object properties: code: type: string description: Code describing the error. doc_link: type: string description: Link to error documentation. field: type: string description: A validation error can specify the field that generated the error. message: type: string description: Detailed message containing information on how to resolve the error. type: type: string description: 'Type of error: validation, tax_authority, warning, general, unknown.' example: validation OnboardingAccepted: type: object properties: job_id: type: string description: The identifier for the job. example: fad3e91a0a46489cbcb82db1693df05b job_status_location: type: string description: Full job URL that can be used for polling. OnboardingAddress: type: object required: - country_code properties: address_line_1: type: string maxLength: 450 description: The primary street address including street name and house number. example: 123 Main Street address_line_2: type: string maxLength: 450 description: Additional address details such as apartment or suite number. example: Suite 400 canton: type: string maxLength: 100 description: A territorial division commonly used in countries like Switzerland. example: Zürich city: type: string maxLength: 100 description: The municipality or urban area where the company is located. example: San Francisco city_code: type: string maxLength: 20 description: A numerical or alphanumerical code representing the city. example: SF123 country_code: type: string description: Country code in ISO 3166-1 two-letter format. example: US district: type: string maxLength: 100 description: A smaller administrative unit within a province, state, or region. example: Financial District neighbourhood: type: string maxLength: 100 description: A specific area or locality within a city or town. example: Downtown number: type: string maxLength: 20 description: The specific number of the building on the street. example: '123' postal_code: type: string maxLength: 100 description: The code used by postal services to identify specific delivery areas. example: '94105' prefix: type: string maxLength: 20 description: An optional element that comes before the street name. example: North province: type: string maxLength: 100 description: The administrative division within a country. example: Ontario region: type: string maxLength: 100 description: A broader geographical area grouping multiple provinces or states. example: Midwest state: type: string maxLength: 100 description: A major administrative division within a country. example: California suffix: type: string maxLength: 20 description: An optional element that comes after the street name. example: Avenue OnboardingCompanyRequest: type: object required: - address - company_number - legal_name - meta properties: address: allOf: - $ref: '#/components/schemas/OnboardingAddress' description: The address where the company is registered. type: object company_number: type: string minLength: 1 maxLength: 50 description: Company's local identification number, usually identical to TIN. example: '123456789' contact_details: allOf: - $ref: '#/components/schemas/OnboardingContactDetails' description: Contact details for the company. type: object establishment_date: type: string description: The date when the company was established (ISO8601 format). legal_name: type: string minLength: 1 maxLength: 450 description: The company's legal name. example: Fonoa Inc. logo: type: string description: URL of the logo to be used in invoice documents for this company. meta: allOf: - $ref: '#/components/schemas/OnboardingMeta' description: Metadata for onboarding the company. type: object representative_email: type: string representative_name: type: string tax_credentials: allOf: - $ref: '#/components/schemas/OnboardingTaxCredentialsRequest' description: Tax credentials to report transactions. Not supported when updating. type: object tax_information: allOf: - $ref: '#/components/schemas/OnboardingTaxInformation' description: Tax information for the company. type: object template_configuration: allOf: - $ref: '#/components/schemas/OnboardingTemplateConfiguration' description: Settings for how your invoicing template will look. type: object trade_name: type: string maxLength: 450 description: The name the company uses to do business. OnboardingContactDetails: type: object properties: certified_email: type: string description: Certified email address for official or legal communications. example: certified@company.com email: type: string maxLength: 250 description: Primary email address for contacting the company. example: contact@company.com phone_number: type: string maxLength: 250 description: Primary phone number for reaching the company. example: '+1-800-123-4567' website: type: string maxLength: 250 description: Official website URL of the company. example: https://www.company.com OnboardingMeta: type: object required: - country_code properties: country_code: type: string description: Country of the entity to be onboarded in ISO 3166-1 alpha-2 format. external_id: type: string description: Additional reference identifier from your own system. Used for idempotency. language_code: type: string description: Language of the entity in ISO 639-1 two-letter format. transaction_purposes: type: array description: 'Workflow operations this company may be used for: document_generation, ta_notification, data_access, record_to_report.' items: type: string webhook: type: string OnboardingTaxCredentialsRequest: type: object required: - certificate_password - certificate_private_key_base64 properties: certificate_base64: type: string description: Base64-encoded certificate issued by the Tax Authority. example: MIIDdzCCAl+gAwIBAgIEbFJ... certificate_password: type: string maxLength: 250 description: Password to unlock the certificate for authentication. example: securePassword123 certificate_private_key_base64: type: string description: Base64-encoded private key corresponding to the certificate. example: MIIEvQIBADANBgkqhkiG9w0B... certificate_type: type: string maxLength: 50 description: Type or format of the certificate (e.g., PKCS#12 or X.509). example: pkcs12 password: type: string maxLength: 2048 description: Password for authentication. example: 'Pa$$w0rdSecure!' pin: type: string maxLength: 2048 description: Personal Identification Number for additional security. example: '1234' username: type: string maxLength: 100 description: Username to authenticate with the Tax Authority. example: tax_user_001 OnboardingTaxInformation: type: object properties: activity_code: type: string description: Code representing the business activity of the entity. example: ACT-200 additional_tax_numbers: type: array description: Additional tax numbers for domestic or foreign operations. items: $ref: '#/components/schemas/OnboardingTaxNumberCountrySpecific' authorization_code: type: string description: Code from tax authorities to authorize tax-related activities. example: AUTH-987654 billing_file_number: type: string description: Unique number assigned to the company's billing file. example: BFN-00123 cash_vat_scheme: type: boolean description: Indicates whether the company is under the cash VAT scheme. device_id: type: string description: Identifier for the device used in tax reporting or invoicing systems. example: DEVICE-456789 eac_code: type: string description: Economic Activity Code representing the nature of business activities. example: '6201' point_of_sale: type: string description: Code representing the company's point of sale. example: POS-1001 regime: type: string maxLength: 10 description: The tax regime under which the company operates. example: VAT tax_code: type: string description: Tax code that complements the tax number. example: TX-001 tax_number: type: string maxLength: 50 description: Tax identification number of the company. example: '123456789' OnboardingTaxNumberCountrySpecific: type: object required: - country_code - tax_number properties: business_model: type: array description: 'Business model: B2B or B2C.' example: B2B items: type: string country_code: type: string description: ISO 3166-1 alpha-2 uppercase country code. example: US country_subdivision_code: type: string description: Code representing a specific subdivision within the country. example: CA tax_number: type: string maxLength: 50 description: Tax identification number for the specified country. example: '123456789' type: type: string description: The type of tax number. OnboardingTemplateConfiguration: type: object required: - color - font - logo_placement properties: color: type: string description: Hexadecimal color value used for the invoice (e.g., 293d62). font: type: string description: Font used for the invoice (e.g., Helvetica World, Open Sans). logo_placement: type: string description: 'Logo placement on the invoice: left or right.' security: - ApiKeyAuth: []