EDU-18211: add B2B Addresses integration guide#2632
Conversation
👁️🗨️ Preview changes on Developer PortalYou can use the link below to load the Developer Portal in preview mode with the changes from this branch: Below is the list of modified pages and their corresponding preview URLs:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| A recipient is a person who can be selected as the order recipient at checkout — they may differ from the user placing the order. Stored in the `contact_information` Master Data v2 entity. | ||
|
|
||
| ### Linking IDs |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Linking IDs"]
There was a problem hiding this comment.
Revise as suggested so that won't be duplicated headings.
| - Deleting a recipient does not affect the addresses referenced through `addressIds`. | ||
| - To find every recipient associated with a given address, query with `_where=addressIds={{addressId}}`. | ||
|
|
||
| ### Operations |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Operations"]
There was a problem hiding this comment.
Revise as suggested so that won't be duplicated headings.
|
|
||
| A location is a specific delivery point within a B2B address (for example, `Dock 3456`, a department, or an internal area). Locations are values of a [custom checkout field](https://developers.vtex.com/docs/guides/custom-fields-integration), stored in the `customFieldValues` Master Data v2 entity. | ||
|
|
||
| ### Linking IDs |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Linking IDs"]
There was a problem hiding this comment.
Revise as suggested so that won't be duplicated headings.
| | `customFieldId` | ID of the location setting (custom field configuration). It must already exist, this API does not create the setting itself. To discover the `customFieldId` for your account, list the existing settings with `GET` [Search custom field settings](https://developers.vtex.com/docs/api-reference/custom-fields-api#get-/api/dataentities/customFieldSettings/search) and pick the one matching the location feature. | | ||
| | `auxId` | ID of the B2B address the location belongs to (the `id` returned by the addresses endpoint). | | ||
|
|
||
| ### Integration notes |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Integration notes"]
There was a problem hiding this comment.
Revise as suggested so that won't be duplicated headings.
| - To move a location to another address, update its `auxId`. To rename it, update its `value`. | ||
| - Deleting a location does not affect its address (`auxId`) or contract (`contractId`). | ||
|
|
||
| ### Operations |
There was a problem hiding this comment.
[markdownlint] reported by reviewdog 🐶
MD024/no-duplicate-heading Multiple headings with the same content [Context: "### Operations"]
There was a problem hiding this comment.
Revise as suggested so that won't be duplicated headings.
| ## Before you begin | ||
|
|
||
| ### Required features |
There was a problem hiding this comment.
An H2 level with no introduction text and a single H3 level could be simplified into a unique heading.
| - **Address** — created first, its `id` becomes the anchor for the other entities. | ||
| - **Recipient** (optional) — references one or more addresses through `addressIds`. At checkout, recipients linked to the chosen address are offered as order recipients. | ||
| - **Location** (optional) — references a single address through `auxId`, plus a contract and a custom field setting. |
There was a problem hiding this comment.
| - **Address** — created first, its `id` becomes the anchor for the other entities. | |
| - **Recipient** (optional) — references one or more addresses through `addressIds`. At checkout, recipients linked to the chosen address are offered as order recipients. | |
| - **Location** (optional) — references a single address through `auxId`, plus a contract and a custom field setting. | |
| - **Address** — Created first, its `id` becomes the anchor for the other entities. | |
| - **Recipient** (optional) — References one or more addresses through `addressIds`. At checkout, recipients linked to the chosen address are offered as order recipients. | |
| - **Location** (optional) — References a single address through `auxId`, plus a contract and a custom field setting. |
| Addresses-->>APP: 200 OK (addressId) | ||
|
|
||
| APP->>Addresses: POST Create recipient (contact_information) | ||
| Note over APP,Addresses: addressIds: [addressId] |
There was a problem hiding this comment.
addressIds: [addressId] wouldn't be better visualized as in addressIds: [Id], following the endpoint's field name?
There was a problem hiding this comment.
Thanks for the careful look! Quick context on the choice — the mermaid notes here are tracing the flow of values between requests, not the schema of the recipient document. Reading top to bottom:
Addresses-->>APP: 200 OK (addressId)— the address creation response hands back anaddressId.Note over APP,Addresses: addressIds: [addressId]— that sameaddressIdis then placed inside theaddressIdsarray of the recipient request.
The next note (auxId: addressId) follows the same pattern: the value from step 1 is reused as auxId when creating a location. So the labels in those notes are deliberately the variable name from step 1, not field names from the destination payload.
I'd also be cautious about switching to addressIds: [Id] because the guide reserves capital-Id for a different concept in the Address linking IDs table — the prefixed form (AD-<uuid>) returned by the POST response. Recipients must store the unprefixed id / DocumentId value, so labeling the array element Id here would risk nudging integrators toward sending the prefixed value.
If the current notation still reads ambiguously, happy to make the value flow more explicit — for example addressIds: [<addressId from step 1>], or adding a one-line note above the diagram. Let me know what reads better!
| - `country`: three-letter [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code (for example, `BRA`, `USA`). | ||
| - `state`: two-letter code (for example, `FL`, `SP`); full names are not accepted. | ||
| - `postalCode`: string in the country's exact format (for example, `02999`, not `2999`); nine-digit formats are not accepted. | ||
| - `receiverName`: required, but slated to be deprecated in favor of [Recipients](#recipients). Fill it with any value (for example, `.`). | ||
| - `geoCoordinates` (optional): array of two doubles (`[lat, lon]`) or `[]`. |
There was a problem hiding this comment.
| - `country`: three-letter [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code (for example, `BRA`, `USA`). | |
| - `state`: two-letter code (for example, `FL`, `SP`); full names are not accepted. | |
| - `postalCode`: string in the country's exact format (for example, `02999`, not `2999`); nine-digit formats are not accepted. | |
| - `receiverName`: required, but slated to be deprecated in favor of [Recipients](#recipients). Fill it with any value (for example, `.`). | |
| - `geoCoordinates` (optional): array of two doubles (`[lat, lon]`) or `[]`. | |
| - `country`: Three-letter [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) code (for example, `BRA`, `USA`). | |
| - `state`: Two-letter code (for example, `FL`, `SP`); full names are not accepted. | |
| - `postalCode`: String in the country's exact format (for example, `02999`, not `2999`); nine-digit formats are not accepted. | |
| - `receiverName`: Required, but slated to be deprecated in favor of [Recipients](#recipients). Fill it with any value (for example, `.`). | |
| - `geoCoordinates` (optional): Array of two doubles (`[lat, lon]`) or `[]`. |
|
|
||
| - `value` has a maximum length of 22 characters. | ||
| - Search requires `_schema=v1`, `_where`, and `_fields`. | ||
| - Build the `_where` filter by combining the linking IDs with `AND`: start from `contractId` and `customFieldId` (the contract and location setting), then optionally add `auxId` to narrow down to a specific address. |
There was a problem hiding this comment.
| - Build the `_where` filter by combining the linking IDs with `AND`: start from `contractId` and `customFieldId` (the contract and location setting), then optionally add `auxId` to narrow down to a specific address. | |
| - Build the `_where` filter by combining the linking IDs with `AND`: Start from `contractId` and `customFieldId` (the contract and location setting), then optionally add `auxId` to narrow down to a specific address. |
Isabella-Veloso
left a comment
Isabella-Veloso
left a comment
There was a problem hiding this comment.
Request changes
Co-authored-by: Isabella Veloso Sá <77300325+Isabella-Veloso@users.noreply.github.com>
2 participants
Adds a new integration guide for the B2B Addresses API under
docs/guides/b2b/b2b-buyer-portal/.The guide explains how the three entities exposed by the API (B2B addresses, recipients, and locations) relate to each other and provides the integration-level details developers need to wire them together.
Related Task
EDU-18211