Clienti

Crea clienti nella tua rete di rivendita. Il cliente riceve un invito via email e sceglie da sé la password: nessuna password transita mai dall'API. Il tuo account deve essere abilitato alla rete clienti; gli altri account ricevono 403 FEATURE_NOT_ENABLED.

POST/customers

Create a customer in your network

In arrivo Il contratto è pubblicato prima dell'implementazione. Questa operazione non è ancora disponibile e la sua forma può ancora cambiare.

Solo per gli account abilitati alla rete clienti. Gli altri account ricevono 403 FEATURE_NOT_ENABLED.

Creates a user in your reseller network and returns its id, to use as customer_id elsewhere. No password is ever sent or returned. The customer is created in the legacy system, then the identity provider sends the invitation email and hosts the page where the customer chooses a password. The invitation is sent right away, in the Accept-Language language, and the link expires after 7 days (proposed). If the invitation cannot be sent the customer is still created and invitation.status is FAILED: call POST /customers/{customer_id}/invitations. The login name is the email. Only available to accounts with the network function (otherwise 403 FEATURE_NOT_ENABLED). First name, last name and email are normalised by the shared rules before they are stored.

Needs the customer-network feature; without it the answer is 403 FEATURE_NOT_ENABLED. The page is public.

Autenticazione: la tua chiave API nell'header X-API-Key.

Parametri

  • Name
    Idempotency-Key
    Type
    string
    obbligatorio
    Description

    Unique key (UUID recommended, max 255 characters) that makes the write safe to retry. A retry with the same key and body returns the first response with Idempotent-Replayed: true; same key with a different body is 422 IDEMPOTENCY_KEY_REUSED; while the first call is running, 409 IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400 IDEMPOTENCY_KEY_REQUIRED.

    length ≥ 1, length ≤ 255.

Corpo della richiesta CustomerCreate

  • Name
    last_name
    Type
    string
    obbligatorio
    Alias italiano: cognome
    Description

    Last name. Normalised by the shared name rules.

  • Name
    first_name
    Type
    string
    obbligatorio
    Alias italiano: nome
    Description

    First name. Normalised by the shared name rules.

  • Name
    address
    Type
    string
    obbligatorio
    Alias italiano: indirizzo
    Description

    Address.

  • Name
    postal_code
    Type
    string
    obbligatorio
    Alias italiano: cap
    Description

    Postal code.

  • Name
    city
    Type
    string
    obbligatorio
    Alias italiano: localita
    Description

    City.

  • Name
    province
    Type
    string
    obbligatorio
    Alias italiano: provincia
    Description

    Province, -- for foreign customers.

  • Name
    country_code
    Type
    string
    obbligatorio
    Alias italiano: nazione
    Description

    ISO 3166-1 alpha-2.

  • Name
    email
    Type
    string (email)
    obbligatorio
    Alias italiano: email
    Description

    Email, trimmed and lower-cased.

  • Name
    phone
    Type
    string
    Alias italiano: telefono
    Description

    Phone.

  • Name
    mobile
    Type
    string
    Alias italiano: cellulare
    Description

    Mobile.

  • Name
    company_name
    Type
    string
    Alias italiano: ragionesociale
    Description

    Company name; if set, vat_number is required.

  • Name
    tax_code
    Type
    string
    obbligatorio
    Alias italiano: codicefiscale
    Description

    Tax code.

  • Name
    vat_number
    Type
    string
    Alias italiano: partitaiva
    Description

    VAT number.

  • Name
    pec_email
    Type
    string
    Alias italiano: fe_pec
    Description

    Certified email (PEC); required with company_name unless foreign.

  • Name
    sdi_code
    Type
    string
    obbligatorio
    Alias italiano: fe_sdi
    Description

    SDI code; 0000000 for private individuals.

  • Name
    bank_name
    Type
    string · nullable
    Alias italiano: banca
    Description

    Bank.

  • Name
    iban
    Type
    string · nullable
    Alias italiano: iban
    Description

    IBAN, required for cash-on-delivery remittances.

  • Name
    account_holder
    Type
    string · nullable
    Alias italiano: intestazioneconto
    Description

    Exact account holder name.

Risposte

  • 201Customer created, invitation sent.Customer
  • 400Malformed or invalid request. Codes: VALIDATION_ERROR (with details.errors), INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_VERSION.Error
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated but not allowed. Codes: FEATURE_NOT_ENABLED (reserved feature not enabled for the customer), IP_NOT_ALLOWED (the key is restricted to other addresses), ACCOUNT_INACTIVE, CUSTOMER_OUT_OF_SCOPE.Error
  • 409State conflict. Codes: OFFER_ALREADY_ORDERED, CUSTOMER_ALREADY_EXISTS (email or tax code already registered), INVITATION_ALREADY_ACCEPTED, IDEMPOTENCY_KEY_IN_USE.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 422The request is well formed but a business rule refuses it. Codes: INSUFFICIENT_CREDIT, SERVICE_NOT_AVAILABLE, CARRIER_NOT_AVAILABLE, IDEMPOTENCY_KEY_REUSED, ...Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Richiesta

POST
/customers
Caricamento...

Risposta 201

{
  "id": "3723",
  "first_name": "Test",
  "last_name": "Tester",
  "email": "customer@example.com",
  "company_name": null,
  "invitation": {
    "status": "SENT",
    "sent_at": "2026-12-09T09:31:59+00:00",
    "expires_at": "2026-12-16T09:31:59+00:00"
  },
  "created_at": "2026-12-09T09:31:59+00:00"
}
POST/customers/{customer_id}/invitations

Send a customer invitation again

In arrivo Il contratto è pubblicato prima dell'implementazione. Questa operazione non è ancora disponibile e la sua forma può ancora cambiare.

Solo per gli account abilitati alla rete clienti. Gli altri account ricevono 403 FEATURE_NOT_ENABLED.

Asks the identity provider to send a new invitation email to a customer who has not chosen a password yet, for example after invitation.status was FAILED or EXPIRED. The previous link stops working. Allowed once per minute. A customer who already accepted gets 409 INVITATION_ALREADY_ACCEPTED; an earlier send less than a minute ago gets 429 RATE_LIMIT_EXCEEDED. NEW capability: the legacy API handed over a password instead.

Needs the customer-network feature; without it the answer is 403 FEATURE_NOT_ENABLED. The page is public.

Autenticazione: la tua chiave API nell'header X-API-Key.

Parametri

  • Name
    Idempotency-Key
    Type
    string
    obbligatorio
    Description

    Unique key (UUID recommended, max 255 characters) that makes the write safe to retry. A retry with the same key and body returns the first response with Idempotent-Replayed: true; same key with a different body is 422 IDEMPOTENCY_KEY_REUSED; while the first call is running, 409 IDEMPOTENCY_KEY_IN_USE. Keys expire after 24 hours. Missing: 400 IDEMPOTENCY_KEY_REQUIRED.

    length ≥ 1, length ≤ 255.

  • Name
    customer_id
    Type
    string
    obbligatorio
    Description

    Customer id.

Risposte

  • 201Invitation sent.CustomerInvitation
  • 401Missing, invalid or expired API key. Codes: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED.Error
  • 403Authenticated but not allowed. Codes: FEATURE_NOT_ENABLED (reserved feature not enabled for the customer), IP_NOT_ALLOWED (the key is restricted to other addresses), ACCOUNT_INACTIVE, CUSTOMER_OUT_OF_SCOPE.Error
  • 404The resource does not exist or is not visible to the caller. Codes: NOT_FOUND and resource-specific ones (SHIPMENT_NOT_FOUND, QUOTATION_NOT_FOUND, CUSTOMER_NOT_FOUND, ...). Resources of other customers are reported as not found.Error
  • 409State conflict. Codes: OFFER_ALREADY_ORDERED, CUSTOMER_ALREADY_EXISTS (email or tax code already registered), INVITATION_ALREADY_ACCEPTED, IDEMPOTENCY_KEY_IN_USE.Error
  • 410Version retired. Code VERSION_RETIRED.Error
  • 429Daily or burst limit exceeded. Code DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED. Wait Retry-After seconds.Error
  • 500Unexpected error. Code SERVER_ERROR; details.correlation_id repeats the correlation id.Error
  • 502The carrier or an internal dependency failed. Code UPSTREAM_ERROR. Safe to retry reads; retry writes with the same Idempotency-Key.Error

Richiesta

POST
/customers/{customer_id}/invitations
Caricamento...

Risposta 201

{
  "status": "SENT",
  "sent_at": "2026-12-10T08:00:00+00:00",
  "expires_at": "2026-12-17T08:00:00+00:00"
}

Modelli

Oggetti usati dalle richieste e dalle risposte di questa pagina.

CustomerCreate

There is no password and no username: the customer logs in with the email and chooses a password from the invitation link.

  • Name
    last_name
    Type
    string
    obbligatorio
    Alias italiano: cognome
    Description

    Last name. Normalised by the shared name rules.

  • Name
    first_name
    Type
    string
    obbligatorio
    Alias italiano: nome
    Description

    First name. Normalised by the shared name rules.

  • Name
    address
    Type
    string
    obbligatorio
    Alias italiano: indirizzo
    Description

    Address.

  • Name
    postal_code
    Type
    string
    obbligatorio
    Alias italiano: cap
    Description

    Postal code.

  • Name
    city
    Type
    string
    obbligatorio
    Alias italiano: localita
    Description

    City.

  • Name
    province
    Type
    string
    obbligatorio
    Alias italiano: provincia
    Description

    Province, -- for foreign customers.

  • Name
    country_code
    Type
    string
    obbligatorio
    Alias italiano: nazione
    Description

    ISO 3166-1 alpha-2.

  • Name
    email
    Type
    string (email)
    obbligatorio
    Alias italiano: email
    Description

    Email, trimmed and lower-cased.

  • Name
    phone
    Type
    string
    Alias italiano: telefono
    Description

    Phone.

  • Name
    mobile
    Type
    string
    Alias italiano: cellulare
    Description

    Mobile.

  • Name
    company_name
    Type
    string
    Alias italiano: ragionesociale
    Description

    Company name; if set, vat_number is required.

  • Name
    tax_code
    Type
    string
    obbligatorio
    Alias italiano: codicefiscale
    Description

    Tax code.

  • Name
    vat_number
    Type
    string
    Alias italiano: partitaiva
    Description

    VAT number.

  • Name
    pec_email
    Type
    string
    Alias italiano: fe_pec
    Description

    Certified email (PEC); required with company_name unless foreign.

  • Name
    sdi_code
    Type
    string
    obbligatorio
    Alias italiano: fe_sdi
    Description

    SDI code; 0000000 for private individuals.

  • Name
    bank_name
    Type
    string · nullable
    Alias italiano: banca
    Description

    Bank.

  • Name
    iban
    Type
    string · nullable
    Alias italiano: iban
    Description

    IBAN, required for cash-on-delivery remittances.

  • Name
    account_holder
    Type
    string · nullable
    Alias italiano: intestazioneconto
    Description

    Exact account holder name.

ParceLabsVersion

CorrelationId

KeyLocale

Location

Postal location used to price a shipment.

  • Name
    postal_code
    Type
    string
    obbligatorio
    Alias italiano: cap
    Description

    Postal code.

  • Name
    city
    Type
    string
    obbligatorio
    Alias italiano: localita
    Description

    City or town.

  • Name
    province
    Type
    string
    Alias italiano: provincia
    Description

    Italian province code. Use -- for foreign addresses.

  • Name
    state_code
    Type
    string
    Alias italiano: codice_stato
    Description

    State or province code. Required for US and CA destinations, otherwise omit.

  • Name
    country_code
    Type
    string
    obbligatorio
    Alias italiano: nazione
    Description

    ISO 3166-1 alpha-2 country code.

IdempotentReplayed

Customer

  • Name
    id
    Type
    string
    obbligatorio
    Alias italiano: id_dva
    Description

    Customer id to use as customer_id.

  • Name
    first_name
    Type
    string
    Alias italiano: nome
    Description

    First name.

  • Name
    last_name
    Type
    string
    Alias italiano: cognome
    Description

    Last name.

  • Name
    email
    Type
    string
    Alias italiano: email
    Description

    Email.

  • Name
    company_name
    Type
    string · nullable
    Alias italiano: ragionesociale
    Description

    Company.

  • Name
    invitation
    Type
    CustomerInvitation
    obbligatorio
    Alias italiano: invito
    Description

    State of the invitation email.

  • Name
    created_at
    Type
    string (date-time)
    obbligatorio
    Alias italiano: timestamp
    Description

    Creation time.

CustomerInvitation

  • Name
    status
    Type
    string
    obbligatorio
    Alias italiano: stato
    Description

    SENT: email sent, link valid. FAILED: the identity provider could not send the email, send it again. ACCEPTED: the customer chose a password. EXPIRED: the link expired, send it again.

    Valori ammessi: SENT, FAILED, ACCEPTED, EXPIRED.

  • Name
    sent_at
    Type
    string (date-time) · nullable
    Alias italiano: inviato_il
    Description

    When the last invitation was sent.

  • Name
    expires_at
    Type
    string (date-time) · nullable
    Alias italiano: scade_il
    Description

    When the link stops working.

BadRequest

Unauthorized

Forbidden

Conflict

Gone

Unprocessable

TooManyRequests

ServerError

BadGateway

NotFound

Was this page helpful?